Scopes & safety

A token carries one or both scopes: read and write. The scope decides what the agent in your editor is allowed to do — and several limits sit behind it so a connected agent can't run away with your account.

What a read token can do

read is always granted and is the default for a new token. With read, the agent can look but not change:

• List your apps and check their status, logs, and deploy readiness.
• Read environment variable names, subdomains, and settings.
• List your products, prices, customers, and connected accounts.
• Pull ready-made wiring prompts for platform features.

A read token can't deploy, stop, restart, or change anything. It's the safe default — connect with read only unless you specifically want the agent to make changes.

What a write token can do

write is a deliberate opt-in you add when you create the token. It's additive: a write token also has read. With write, the agent can make real changes:

• Create, deploy, stop, and restart apps.
• Change app settings, environment variables, subdomains, and branches.
• Create and update products and prices, and set up integrations.

These are the same actions you can take in the dashboard. Give write only to an editor you trust, and prefer a short expiry.

What stops a runaway agent

Read and write both sit behind the same guards.

The host approval dialog. Before your editor calls a tool, it shows you the tool — its name and description — and asks you to approve, and many hosts can remember the choice per tool. Those descriptions are long and explicit on purpose: they're written for the model so it picks the right tool and the right arguments, and so what you approve is unambiguous. Read the description in that dialog before you approve — it says exactly what the tool will do. Hosts that connect over OAuth show the same list up front: the consent screen has a Show tools control that expands every tool the connection can use.

Rate limits, per token. Each token gets a fixed budget per minute:

• 30 read calls per minute
• 10 write calls per minute

Go over and the call is refused with a message the agent can read and back off on — not a hard error that kills the turn:

Rate limited — this access token has used its read budget of 30 calls per minute. Wait 42s and try again, and do not retry in a loop.

A well-behaved agent waits and continues. (Reading the docs through a connected agent counts against the same read budget.)

Retry safety on writes. Transport hiccups and model retries mean a write tool can be called twice in quick succession. OrbitOrca collapses a duplicate write within a 30-second window: calling deploy_app twice within 30 seconds deploys once — the second call returns the first result instead of running again. A deliberate re-call later (say, setting a subdomain back to a previous value) is outside the window and runs normally.

Revocation. Revoke a token from the dashboard and it stops working immediately, without touching your other tokens. Do it the moment a token might be exposed. See Tokens.