Authentication
Creating API keys, the two ways to send them, what they are scoped to, and how to handle them safely.
Every programmatic surface — REST, MCP and the agent endpoints — authenticates with the same API key.
Creating a key
ProGo to Integrations in the account menu, or Team → Integrations. Give the key a name that says where it will be used — Slack integration, Warehouse sync, Claude Desktop — and create it.
The full key is shown once, at creation. It is stored only as a hash, so there is no way to recover it afterwards. If you lose it, revoke it and create another.
Keys look like this:
cad_live_XCq0vJ5f1mR7wZ2s...The listing afterwards shows only a short prefix, the name, when it was created, and when it was last used.
Sending a key
Two ways, both equivalent.
The normal way. Prefer it everywhere you can set headers.
curl https://cadence.alen.world/api/v1/projects \
-H "Authorization: Bearer cad_live_..."The REST API accepts the key only in the Authorization header. A key in a query string ends up in browser history, proxy logs and server access logs — places you cannot purge — so /api/v1 no longer reads one.
The MCP endpoint is the single exception, because some MCP-over-HTTP clients cannot set headers at all:
https://cadence.alen.world/api/mcp?key=cad_live_...Prefer the header there too whenever your client supports it, and rotate any key you have previously sent in a URL.
What a key is scoped to
A key is bound to:
- the team that owns it — every request is filtered to that workspace, and
- the user who created it — actions taken with the key, such as comments, are attributed to that person.
If the creating user leaves, revoke their keys and issue new ones under someone who is still there.
Revoking and expiry
Revoke a key from Integrations at any time; it stops working immediately. Keys carry an optional expiry, and an expired or revoked key is rejected the same way an invalid one is.
Keys record a last used timestamp, which is the quickest way to find the ones nobody needs any more.
Authentication failures
| Status | Message | Cause |
|---|---|---|
401 | Missing or invalid API key | No Authorization: Bearer cad_live_… header (on /api/mcp, also no ?key=) |
401 | Invalid API key | The key does not match any key on record |
401 | API key has been revoked | Revoked in Integrations |
401 | API key has expired | Past its expiry date |
403 | API access requires a Pro or Enterprise plan | The key is valid, but its team is on the free plan |
Handling keys safely
- Keep keys in environment variables or a secrets manager — never in source control, and never in client-side code.
- Issue one key per integration, so you can revoke a single system without breaking the others.
- Rotate on any suspicion of exposure: create the replacement, deploy it, then revoke the old one.