The API key is the credential your systems use to authenticate against the Whalemate API. This article explains where it's generated, how it's used, what it enables, and how it's revoked. The endpoints for each API are covered in their own articles.
Authenticate calls from your systems to the Whalemate API.
Integrate payroll, enrollments, and security events with your own tools.
Cut off access for a specific integration without affecting the others, if you gave each one its own key.
This feature is enabled on a per-company basis. If you don't see the API Keys card in Settings → Integrations, contact us and we'll enable it on your account.
Navigation: Settings → Integrations → API Keys card → Active Keys button
The Active Keys list opens, showing the keys you already have.
Click Add new. The New API Key dialog opens.
Fill in the Description. It's required, and it's best to put the name of the system that will use the key: it's the only thing you'll see afterward to tell one key apart from another.
Click Create Key.
The key appears in full, with a button to copy it.
The key is shown only once. The dialog itself warns you: "This API key is shown only once. Copy it and store it securely in a protected location. If you lose it, you'll need to generate a new key." Copy it and save it before closing the dialog.
The key is sent in the X-API-KEY header of every call:
X-API-KEY: your_api_key
If the call doesn't include the header, the API responds with 401 and API Key required.
If the key doesn't exist or has been revoked, it responds with 403 and Invalid API Key.
With a valid key, an external system can:
View enrollments in courses and learning paths.
View campaigns and their events.
View reported emails and their analytics.
View, create, modify, and delete collaborators.
View, create, modify, and delete groups.
Log custom security events.
A single key enables all of that together. You cannot generate a read-only key, or limit it to a part of the API. Treat it as an admin-level credential: store it the way you'd store a system password, don't paste it into a repository or a ticket, and give each integrated system its own key. That way, the day you need to cut off access for one, you can revoke its key without touching the others.
The list has two columns and one action:
Key — shows only the last 5 characters, preceded by dots. The full key can't be viewed again from the platform.
Description — the one you wrote when creating it.
The row's trash icon revokes that key.
Keys don't expire. A key remains valid indefinitely until you delete it, so it's a good idea to review the list from time to time and remove any that belong to systems you no longer use.
Keep descriptions up to date. It's the only piece of information that lets you know which system each key belongs to, and without it you won't be able to decide which one is safe to revoke.
In the Active Keys list, click the row's trash icon. The confirmation "Are you sure you want to delete this API key?" appears.
Once confirmed, the key stops working immediately. Calls using it will start receiving a 403 error. Notify whoever maintains that integration before revoking it, or do it only after you've replaced it with a new one.
To rotate a key without interrupting service: generate the new one, configure it in your system, verify that calls work correctly, and only then revoke the previous one.
I lost the key. Can I view it again?
No. The full key is shown only when it's created. Generate a new one, configure it in your system, and then revoke the previous one from the list.
Do keys expire?
No. They remain valid until you delete them.
Can I create a read-only key, or one limited to part of the API?
Not currently: all keys enable the same access. If you need permissions separated by integration, let us know and we'll take it into account.
How many keys can I have?
There's no limit. We recommend one per system, so you can revoke them independently.
How do I know if a key is still being used?
The list doesn't show last usage, so the only reference is the description. That's why it's a good idea to write down the system it belongs to, and update it whenever that changes.
Have feedback or want to request improvements? Let us know at roadmap.whalemate.com/roadmap