> 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.

# Authentication

Every request needs one credential in the `Authorization` header, except `GET /v2/health`:

```text
Authorization: Bearer <credential>
```

## Credentials

| Credential      | Form                        | Where it comes from                                                                        | Lifetime                                  |
| --------------- | --------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------- |
| API key         | `crk_{env}_{slug}_…`        | Dash. Read [API keys](/paperwork/v2/keys).                                                 | Until you revoke it, or until its expiry. |
| Exchanged token | `crt_…`                     | `POST /v2/oauth/token`. Read [OIDC trusts](/paperwork/v2/oidc-trusts).                     | 900 seconds by default.                   |
| OIDC token      | A JWT from a trusted issuer | Your workload. Read [OIDC trusts](/paperwork/v2/oidc-trusts#send-the-oidc-token-directly). | Set by the issuer.                        |

Each host accepts only the credentials of its own organization. A key of another organization gets `401 invalid_api_key`.

## Read the credential

`GET /v2/me` returns the credential of the request. It needs no scope.

```bash
curl -s "https://$CRK_SLUG.cloudraker.run/v2/me" \
  -H "Authorization: Bearer $CRK_API_KEY"
```

```json
{
  "slug": "acme",
  "env": "live",
  "scopes": ["parse", "extract", "jobs:read"],
  "key": { "id": "key_01JC9M…", "name": "invoices", "hint": "a1B2c3" }
}
```

For a `crt_` token or a JWT, `key.id` holds the trust id, and `key.hint` is empty. The Run issuer of your organization has the trust id `self`.

## Scopes

A credential has a list of scopes. There is one list for the host.

| Group      | Scopes                                                                                                                      | Grants                                                                                                          |
| ---------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Capability | `parse`, `extract`, `classify`, `split`, `fill`, `redact`, `generate`, `convert`, `redline`, `sign`, `transcribe`, `agents` | The capability of the same name.                                                                                |
| Jobs       | `jobs:read`                                                                                                                 | List the jobs of the environment of the credential. Read the jobs of other credentials in the same environment. |
| Run        | `run`, `read`, `cancel`, `git`, `secrets`, `admin`, `preview`, `act_as`                                                     | Run paths on the same host.                                                                                     |

A missing scope gives `403 insufficient_scope`. The agent allowlist and the rate cap of a key are restrictions on the key. They are not scopes.

## Common errors

| Status | Code                 | Cause                                                                 |
| ------ | -------------------- | --------------------------------------------------------------------- |
| `401`  | `missing_credential` | No `Authorization` header.                                            |
| `401`  | `invalid_api_key`    | A bad `crk_` key, a key of another host, or a revoked or expired key. |
| `401`  | `invalid_token`      | A `crt_` token or a JWT that fails a check.                           |
| `403`  | `insufficient_scope` | The credential does not have the scope, or the agent is not allowed.  |

Read [Errors](/paperwork/v2/errors) for all codes.