Authentication and API keys
View as MarkdownEvery REST request sends an API key in the Authorization header:
Authorization: Bearer blitframe_...
A request without a valid key gets 401. The MCP server accepts the same keys. It also lets apps such as Claude connect by signing in with your Code Artworks account.
Create a key
Open Console → API keys and create a key. Keys can only be created there. Neither the API nor the MCP server can create them, so a leaked key or a connected app cannot hand out new keys.
| Rule | Detail |
|---|---|
| Secret | Shown once. Store it in a secret manager. Blitframe keeps only a hash. |
| One key per app | Create one key per app or agent, so you can revoke one without affecting the others. |
| How many | A workspace can have 25 active keys. |
| Expiry | After 30 days, 90 days or a year, or never. Once a key expires, requests that use it get 401. |
Who owns a key
Keys belong to the workspace, not to the person who created them. They keep working when that person signs out.
When someone leaves the workspace, or is removed from it in the console, a "revoke their keys" box decides what happens to the keys they created:
- Ticked (the default): the keys are revoked.
- Unticked: the keys keep working and are marked
creatorLeft: truein the key list. That person may still have the secret, so replace such a key. Create a new one, switch your app to it, then revoke the old one.
List and revoke keys
| Method | Path | Does |
|---|---|---|
GET |
/v1/api-keys |
Active keys, newest first. Secrets and expired keys are never listed. |
DELETE |
/v1/api-keys/{apiKeyId} |
Revoke a key. Requests that use it get 401 from then on. |
The MCP tools are list_api_keys and revoke_api_key. Each listed key has:
| Field | Meaning |
|---|---|
id, name |
The key's id and name |
prefix |
The start of the secret: blitframe_ and the 7 characters after it, such as blitframe_k3Xq9Lm. Use it to tell keys apart. |
createdAt, lastUsedAt |
When the key was created and last used |
expiresAt |
When the key stops working, or null if it never expires |
createdBy |
The email of the person who created the key, or null once that person belongs to no Blitframe workspace any more |
creatorLeft |
true when the person who created the key is no longer in the workspace (who owns a key) |
If a key may have leaked, revoke it at once and create a new one.
Who can revoke which key
| Action | With an API key | Signed-in MCP connection | Console |
|---|---|---|---|
| List the workspace's keys | Yes | Yes | Yes |
| Revoke the key making the request | Yes | Not applicable | Not applicable |
| Revoke a key you created | No: 403 key_cannot_revoke_keys |
Yes | Yes |
| Revoke a key someone else created | No: 403 key_cannot_revoke_keys |
No: 403 key_cannot_revoke_keys |
Yes |
So a leaked key can retire itself but cannot lock out your other keys, and a connected app can revoke only your own keys. The two /v1/api-keys endpoints also accept the access token of an app connected with your Code Artworks account, with the rights in the signed-in column.