Skip to content

API keys

How API keys authenticate calls to the Coassemble API, and how to create, name, rotate and revoke them.

How do API keys work?

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 last few characters shown so you can tell them apart.
  • Created date.
  • Last used date, which makes it obvious which keys are dormant.
  • Status, active or revoked.

Keys you already had keep working and appear in the list automatically.

How do I create an API key?

  1. Open Developer, then API keys.
  2. Click Create key.
  3. Give the key a name that says where it will be used. Something like "Production backend" or "Staging import job" beats "Test key 3".
  4. 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.
  5. Keep the key out of source control.

How do I use an API key?

Include the Authorization header in your REST API requests. The header value is your key, in this shape:

Authorization: COASSEMBLE:[workspace ID]:[key]

Most HTTP clients let you set headers directly, like this in curl:

curl https://api.coassemble.com/v1/... \
  -H "Authorization: COASSEMBLE:[workspace ID]:[key]"

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.

  1. 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".
  2. Copy the key straight away and store it in your secret store.
  3. Deploy the new key to every service, job and environment that calls Coassemble. Missing one is the most common reason a rotation fails.
  4. 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.
  5. Check the old key's Last used date on the API keys tab. Once it stops moving, nothing is calling with it.
  6. 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.

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 a planned rotation with overlap is the wrong shape here.

  1. Revoke the exposed key from the API keys tab.
  2. Create a replacement, deploy it, and confirm your traffic recovers.
  3. 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, though it filters by time, status, path and client identifier rather than by key. If you can't tie a key to a service, that's the signal to replace it with one that's named.