Keys and scopes

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

Authorization: Bearer rk_xxx

Owners and admins make keys in Settings → Integrations → API keys. A key is rk_ followed by 48 letters and digits. 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.

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.

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

What a key can see

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