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 per company. If you don't see the API Keys card under 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. New API Key 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 full key appears, 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 will 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 each call:
X-API-KEY: tu_clave_api
If the call doesn't include the header, the API responds with 401 and API Key required.
If the key doesn't exist or was revoked, it responds with 403 and Invalid API Key.
With a valid key, an external system can:
Query enrollments in courses and learning paths.
Query campaigns and their events.
Query reported emails and their analytics.
Query, create, modify, and delete collaborators.
Query, create, modify, and delete groups.
Log custom security events.
A key enables all of that together. You can't generate a read-only key, nor limit it to a portion of the API. Treat it as an administrator credential: store it the way you would store a system password, don't paste it into a repository or a ticket, and give each system that integrates a different key. That way, the day you need to cut off access for one, you 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 trash icon in the row 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 periodically and remove those that correspond to systems you no longer use.
Keep the descriptions up to date. It's the only piece of information that tells you which system each key corresponds to, and without it you won't be able to decide which one can be revoked.
In the Active Keys list, click the trash icon in the row. 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 after you've already replaced it with a new one.
To rotate a key without interrupting the service: generate the new one, configure it in your system, verify that the calls work, and only then revoke the previous one.
I lost the key. Can I see 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 a portion of the API?
Not currently: all keys enable the same things. If you need permissions separated by integration, contact us and we'll take it into account.
How many keys can I have?
There's no limit. The recommendation is 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 the last usage, so the only reference is the description. That's why it's a good idea to write in it the system it corresponds to, and update it when that changes.
Do you have feedback or want to request improvements? Let us know at roadmap.whalemate.com/roadmap
Technical reference for managing employees (target collaborators) from external systems: list, create, update, delete, and view their campaign event history via the Whalemate API.
Technical reference for querying simulation campaigns and their event history from external systems through the Whalemate API.