Authentication and API keys

View as Markdown

Every 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: true in 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.