API keys
How API keys authenticate calls to the Coassemble API, and how to create, name, rotate and revoke them.
What does an API key do?
An API key authenticates calls to the Coassemble API. A workspace can hold as many keys as it needs, so you can name one per integration and revoke any of them without disturbing the others.
Where do I find my API keys?
Open Developer, then API keys. Each key in the table shows:
- Name, so it's clear which integration uses it.
- Key, masked, with the first few characters shown (it starts with
COASSEMBLE:) so you can tell them apart, plus a Production or Test label. - Created date.
- Last used date, which makes it obvious which keys are dormant.
- Status: Active, Not yet in use or Revoked.
Keys you already had keep working and appear in the list automatically.
How do I create an API key?
- Open Developer, then API keys.
- Click Create key.
- Give the key a name that says where it will be used. Something like "Production backend" or "Staging import job" beats "Test key 3".
- Under Key type, choose Production (the default) for your live integration, or Test for building and testing. A test key never bills, only sees test learners, and keeps its completions out of reports and exports. You can't change a key's type later. If your workspace can only issue test keys, this choice doesn't appear.
- Copy the key straight away and store it in your integration's secret store. The table only ever shows the masked version afterwards, so if you lose the full key you'll need to create a new one.
- Keep the key out of source control.
How do I use an API key?
Paste the whole key, exactly as you copied it, as the value of the Authorization header on every REST API request. The key already includes your workspace ID (it looks like COASSEMBLE:<workspace ID>:<secret>), so don't add the workspace ID separately, and don't add "Bearer". For the full set of endpoints and request shapes, see the developer documentation.
How do I keep a key secure?
A key lets whoever has it call the Coassemble API on behalf of your workspace. Treat it like a password.
- Don't commit it to public repositories.
- Don't include it in client-side code, meaning anything that runs in the browser or on the learner's device.
- Use a backend proxy when calling the API from a web app, so the key stays on your server.
- Name a key per integration, so if one leaks you can revoke just that one.
How do I rotate a key without downtime?
Overlap the new key with the old one. Create the replacement, deploy it, confirm nothing is still calling with the old key, then revoke it. Rotating with a gap risks failed requests, and revoking before you've checked risks the same.
A workspace can hold several keys at once, so the old and new keys work side by side for as long as you need them to.
- Open Developer, then API keys, and click Create key. Name it so you can tell it apart from the one it replaces, for example "Production backend, Sept 2026".
- Copy the key straight away and store it in your secret store.
- Deploy the new key to every service, job and environment that calls Coassemble. Missing one is the most common reason a rotation fails.
- Open the Requests tab and confirm your traffic is flowing on the new key. Give it long enough to cover anything that runs on a schedule: nightly jobs, weekly rollups, monthly exports.
- Check the old key's Last used date on the API keys tab. Once it stops moving, nothing is calling with it.
- Revoke the old key.
A revoked key stops working immediately. If something you missed starts failing, create a fresh key, update that service, and rotate again from step 4.
Why can I delete some keys but only revoke others?
A key that has never been used (status Not yet in use) shows Delete, so you can remove it straight away. A key that has been used shows Revoke. Once it's revoked, you can delete it too. This stops a live integration losing its key in one step.
What do I do if a key has leaked?
Revoke it now and accept the downtime. A leaked key keeps working for whoever has it until you revoke it, so don't wait for a planned rotation with overlap.
- Revoke the exposed key from the API keys tab.
- Create a replacement, deploy it, and confirm your traffic recovers.
- Open the Requests tab and look back over the period the key was exposed, for calls you don't recognise: requests at times, or against paths, that don't match your own traffic.
Treat a key as exposed if it has been committed to a repository, pasted into a ticket or a chat, included in client-side code, or shared with anyone outside the team that manages the integration. If you're unsure whether a key is exposed, rotate it.
When should I rotate?
Set the interval to whatever your security policy calls for. Outside that schedule, rotate when:
- Someone with access to the key leaves, or moves off the integration.
- A key has been exposed, on any of the grounds above.
- A key has no clear owner. If its Last used date is recent but nobody can say which service is calling, replace it with a named key so the next person can.
- Several integrations share one key. Create a named key for each one, deploy them, then retire the shared key. After that a single leak only ever costs you one integration.
Frequently asked questions
Do my existing keys still work?
Yes. Keys created before named keys existed keep working and appear in the list alongside any new ones.
Does revoking one key affect the others?
No, as long as each integration has its own key. Revoking a key leaves every other key working. If several services share a key, all of them stop when it's revoked, which is the reason to name a key per integration.
How do I work out which service is using a key?
The Last used date on the API keys tab tells you whether a key is still being called at all. The Requests tab logs every call that was made, so you can see what's still flowing. It filters by time, status, path and client identifier, not by key. If you can't tie a key to a service, that's the signal to replace it with one that's named.