# Keys and scopes

What an API key can see and do, how scopes work, and why someone's private inbox answers 404.

Rookery for developers · Updated October 11, 2026 · https://userookery.com/developers/keys-and-scopes/

Every request needs an API key, sent in the `Authorization` header:

```http
Authorization: Bearer rk_xxx
```

Owners and admins make keys in **Settings → Integrations → API keys**. A key is `rk_live_` or `rk_test_` followed by 48 letters and digits (keys made before test keys are `rk_` and 48, and work as live keys). It's shown once, when you make it. Rookery keeps only a hash of it, so nobody can show it to you again; if you lose it, make a new one.

## Live keys and test keys

- A **live key** (`rk_live_…`) works on your real mail.
- A **test key** (`rk_test_…`) works only on the [sandbox](https://userookery.com/developers/sandbox/): its own inbox, where nothing is ever sent. It can't see your real mail, and live keys can't see the sandbox.

Choose under **Works on** when you make the key. Build and run your tests with a test key, then switch to a live key with the same scopes.

## A key is a teammate

Each key joins your team as its own agent, named after the key. Its notes, tags, drafts and other changes show up under that name in conversations and in the audit log, next to Scout, Quill and Fetch. You can assign conversations to it, too.

## Scopes: what a key may do

You choose a key's scopes when you make it. They can't be changed later: make a new key and revoke the old one.

| Scope | In Settings | Lets the key |
|---|---|---|
| `read` | **Read** | List and read conversations, notes, tags, inboxes and documents |
| `write` | **Work on conversations** | Add notes, change status, tag and assign |
| `draft` | **Draft replies** | Write replies and document requests that wait for a person's yes |
| `send` | **Send replies** | Send them, after a 10-minute undo window |

- **Read** is always included when you choose anything else.
- A call without the scope it needs gets `403`, and the message names the scope.
- `reply` and `request_documents` need `draft`, or `send` when you pass `send: true`.
- For trying things, and for most agents, start with **Read** alone, or **Read** and **Draft replies**. See [Draft, don't send](https://userookery.com/developers/draft-dont-send/).

## What a key can see

A test key sees only the sandbox. A live key sees what the person who made it sees:

- every team inbox, and
- that person's own private inboxes.

Someone else's private inbox doesn't exist for the key. Asking for one of its conversations answers `404`, the same as an id that was never there, whatever the key's scopes. So a key can't tell whether a private conversation exists.

Lists only include what the key can see, and so do the open counts on inboxes and tags.

## Keep keys safe

- Give each app or agent its own key, with only the scopes it needs.
- Keep keys on a server or in an environment variable. Never put one in a web page, a mobile app or a repository.
- **Settings → Integrations → API keys** shows when each key was last used.
- Click **Revoke** to stop a key straight away. Everything it did stays in the audit log.