Keys and authentication

-H "Authorization: Bearer $UNDERSTANDING_API_KEY"

headers: {
  Authorization: `Bearer ${process.env.UNDERSTANDING_API_KEY}`,
}

headers={"Authorization": f"Bearer {os.environ['UNDERSTANDING_API_KEY']}"}

# Keys and authentication

Built and tested, not yet deployed. Early access.

## Bearer keys

Every request carries the header `Authorization: Bearer <your key>`.

The header in cURL:

```bash
-H "Authorization: Bearer $UNDERSTANDING_API_KEY"
```

The header in TypeScript:

```typescript
headers: {
  Authorization: `Bearer ${process.env.UNDERSTANDING_API_KEY}`,
}
```

The header in Python:

```python
headers={"Authorization": f"Bearer {os.environ['UNDERSTANDING_API_KEY']}"}
```

How the key is checked:

- The word `Bearer` can be in any case, and spaces around the key are trimmed.
- Keys start with `usk_live_`.
- We keep only a hash of each key, so a key is shown once, when it’s made. Store it then.
- A revoked key stops working on its next call.

For a client that can’t send the header that way, two other forms work:

- `Authorization: <your key>`: the key alone, with no `Bearer` and no spaces.
- `x-api-key: <your key>`, read only when the request has no `Authorization` header.

## Access tokens from connected apps

When a person connects an app to their account through OAuth, the app calls with an access token in place of a key, in the same header. Access tokens start with `uat_` and last an hour; the app refreshes them.

- A token is metered to the account and rate limited like a key: each connected app counts as one key.
- A token works only at the address it was issued for.
- Revoking the app’s connection in the console stops its tokens.

## Getting and rotating keys

You make and revoke keys in the console, which isn’t open yet. [Console and keys](/api/docs/console)

An account can hold up to 10 active keys. To rotate one, make a new key, move your servers to it, then revoke the old key: both work in between.

[Get early access](/api#early-access)

## Keeping keys safe

- Call the API from your server only. Never ship a key in a browser or mobile app.
- Keep the key in an environment variable or your secrets store, not in code.
- Give each service its own key, so you can revoke one without stopping the others.

## Responses

| Status | Message | When |
| --- | --- | --- |
| `401` | `Send your API key or access token as a Bearer token. Get a key at <console address>.` | No credential: neither an `Authorization` nor an `x-api-key` header, or an `Authorization` value with a space in it that isn’t `Bearer <key>`. |
| `401` | `That API key isn't valid or was revoked.` | A key we don’t recognise, or one that was revoked. |
| `401` | `That access token isn't valid, has expired or was revoked.` | An access token (`uat_…`) we don’t recognise, one past its hour, or one whose app connection was revoked. |
| `401` | `That access token was issued for a different MCP URL.` | A token issued for another of our addresses. |
| `503` | `The API is starting up. Try again in a moment.` | We couldn’t check the key or token just then. Retry with backoff. |

Every 401 carries the header `www-authenticate: Bearer realm="understanding-api"`.

Source: /api/docs/authentication