> This page is for Paperwork API, version v2.
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.cloudraker.com/paperwork/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# API keys

An API key belongs to your organization, not to a person. Only an admin can create a key. Dash manages the keys.

## Format

```text
crk_{env}_{slug}_{secret}{tag}
```

| Part     | Example        | Meaning                                                          |
| -------- | -------------- | ---------------------------------------------------------------- |
| `env`    | `live`, `test` | The environment of the key.                                      |
| `slug`   | `acme`         | The slug of your organization. The host must have the same slug. |
| `secret` | 43 characters  | The secret part of the key.                                      |
| `tag`    | 6 characters   | A checksum. The API drops a forged key before any other work.    |

A key does not work on the host of another organization. A key with a bad format or tag gets `401 invalid_api_key`.

## Create a key

1. Open [API keys](https://dash.cloudraker.com/api-keys) in Dash.
2. Select **Create key**.
3. Enter a name and select the environment and the scopes.
4. Copy the value.

Optional settings:

| Setting         | Effect                                                                        |
| --------------- | ----------------------------------------------------------------------------- |
| Expiry          | The key stops working at this time.                                           |
| Rate cap        | The key has its own requests-per-minute limit, inside the organization limit. |
| Agent allowlist | The key can start only these Run agents.                                      |

> **Warning**
>
> Keep a key on your server. Never put a key in a browser, a mobile app or a repository.

## Live keys and test keys

| Behaviour            | Live key                | Test key                                                       |
| -------------------- | ----------------------- | -------------------------------------------------------------- |
| Rate limits          | The limits of your plan | Its own limits. Read [Rate limits](/paperwork/v2/rate-limits). |
| Jobs                 | Real jobs               | Real jobs. Test keys run the same capabilities.                |
| Paperwork credits    | Real credits            | Real credits                                                   |
| Value in Dash        | Shown one time only     | Can be shown again                                             |
| Run and `/v2/agents` | Allowed                 | Refused with `403 test_key_not_allowed`                        |

> **Warning**
>
> Test keys have their own rate limits, but their jobs use real paperwork credits.

A test key does not give a sandbox. Paperwork has no test credit pool. When the balance of the organization reaches zero, live keys and test keys both get `402 credits_exhausted`.

## Revoke a key

Select a key in Dash and revoke it. Revocation applies on the next request. An open [job stream](/paperwork/v2/streaming) of the key ends with no terminal event and no job output.

To rotate a key, create the new key, deploy it, then revoke the old key. Dash shows the last-used time of each key.