Choose token scopes

What it is

A scope is a permission attached to an API key. When you create a key you tick the scopes it may use, and the API refuses anything outside that set with a 403 and a machine-readable insufficient_scope code.

Scopes are fixed at creation. There is no "edit permissions" on an existing key — widening a key would defeat the point of having narrowed it. To change what a key can do, create a new one and revoke the old.

When you would use it

Pick scopes every time you mint a key, and revisit them whenever an integration changes shape. The rule is boring and correct: grant the fewest scopes that make the integration work.

Where to find it

Open Dashboard → Settings → Developer → Create API key. The scopes appear as a checkbox list under Permissions.

The scopes you can grant

Scope	What it allows
knowledge:read	Read knowledge sources and collections
knowledge:write	Add, update, and remove knowledge — including the ingest endpoint
chatbots:read	Read chatbots, conversations, queries, and analytics
chatbots:write	Create and update chatbots and their settings
chat:send	Send messages to a chatbot and get answers
widget:manage	Read a chatbot's widget token and manage its allowed domains
billing:read	Read plan, subscription, and usage information

Two notes that are easy to miss:

• The read and write scopes on a resource are an either/or for most read routes: a route that accepts chatbots:read also accepts chatbots:write, because write implies read. Grant the read scope alone when the integration only reads.
• billing:read is genuinely read-only. There is no billing:write, so no key can start a checkout, change a plan, or open the payment portal. Those stay with the owner in the dashboard.

Scopes that are deliberately withheld

Several permissions exist inside the product but are never available to a self-service key:

• Team management. A key cannot invite, edit, or remove members.
• Your own account surface. A key cannot read or change the owner's profile, email, phone, or two-factor settings, and cannot sign sessions out.
• Key management. A key cannot create or revoke keys. If it could, the scope model would only be one request deep — a narrow key could mint a wide one.
• The public widget chat scope. That belongs to Agentency's own widget machinery, which authenticates with the widget token and the allowed-domain list, not with your key.
• Anything outside your own workspace. A key is bound to the account that created it and cannot reach beyond it.

If an integration seems to need one of these, the design is wrong somewhere. Team changes and billing changes are owner actions in the browser, on purpose.

Steps

1. Write down what the machine must actually do, as verbs: "upload the changelog nightly", "register this site's domain", "answer questions from our support tool".
2. Map each verb to the smallest scope. Ingest → knowledge:write. Site plugin → widget:manage. Reporting → the :read scopes only.
3. Create the key with exactly those boxes ticked.
4. Store the secret and run one real call per verb to confirm nothing is missing.
5. If a call returns insufficient_scope, read details.required_any_of in the response — it lists the scopes that would have been accepted.
6. Create a replacement key with the missing scope and revoke the first one. Do not keep a wide key "just in case".
7. Record which system holds which key, so a future clean-up does not become guesswork.

Worked examples

A WordPress or storefront plugin. Grant widget:manage and nothing else. That is enough to read the widget token and register the site's domain, and it deliberately cannot create, edit, or delete a chatbot. A plugin lives on a server you do not fully control, so chatbots:write there is a genuine risk rather than a theoretical one.

Nightly knowledge sync from your CMS. Grant knowledge:write. Add knowledge:read only if the job needs to list what already exists before deciding what to push.

A reporting job. Grant chatbots:read, and billing:read if the report includes usage. It cannot change anything.

Your own product asking the chatbot questions. Grant chat:send alone. It does not need chatbot-management scopes, and answers sent this way spend message credits exactly like a visitor's — see How message credits work.

What you will see

The create dialog lists the grantable scopes as labelled checkboxes with plain-language descriptions. Withheld scopes are not shown at all — you cannot tick what is not offered.

Afterwards the Developer table shows each key's scopes in its own column, so an over-wide key is visible at a glance.

Limits and plan notes

Scopes are checked on top of everything else, not instead of it. A key with knowledge:write still obeys your plan's knowledge limits, still cannot touch another account's data, and is still rate-limited.

A key always acts on the account of the person who created it. Scopes narrow what it may do; they never widen where it may go.

A 403 for scope and a 402 for a plan limit are different failures. Check error.code before assuming a permission problem.

Common problems

I need to add a scope to an existing key.

Not possible. Create a new key with the full set, deploy it, then revoke the old one.

The plugin can see more than I expected.

The key is too wide. Issue a widget:manage key and revoke the broad one.

insufficient_scope on a route I thought was read-only.

Read details.required_any_of in the error body. Some management routes accept either the read or the write scope for the resource; a key with neither is refused.

Why can my key not invite a teammate?

Team management is withheld from self-service keys. Do it in the dashboard.

Can a key switch into a client's account like I do?

No. The account switcher is a browser feature. A key is bound to its owner's workspace, so each account needs its own key, created by that account's owner.

Is billing:read safe to grant?

It exposes plan and usage figures for the account. It cannot spend anything. Grant it only if your integration genuinely reports on usage.