# Authentication and API keys

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](/docs/blitframe/mcp) 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](#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.
