Scopes and least privilege

Every gavAI API endpoint requires a scope, and every token carries the exact scope set it was minted with — nothing more. This page is the catalogue: it names each action verb, lists every scope and the endpoints it gates, and walks the four steps to mint a key that can do only what your integration actually needs. By the end you will be able to look at an endpoint and name the smallest scope set that calls it. The shape to hold in your head: scopes follow <resource>:<action>. Resources are things like pages, secrets, domains. Actions are one of four verbs. Workspace API keys are minted with an explicit scope set; OAuth session tokens inherit the authenticated user’s permissions for the active workspace.

​

The four action verbs

​

The implication chain

:destructive implies :write, and :write implies :read. A token granted tokens:destructive can also read and write tokens — it holds the full chain. The chain is a convenience for the broad cases. The recommendation is the opposite: grant the narrowest verb that does the job. If your integration only lists tokens, grant tokens:read and stop. Broad grants compound over time, and a key that holds more than it needs is the one that hurts when it leaks.

​

Scope catalogue

Every endpoint in the public API is in this table. If you can’t find an endpoint here, it’s not callable with an API key — it’s an internal route or requires an OAuth session.

​

Why secrets:set is its own verb

Secrets break the implication chain on purpose. A secret value is write-only — once stored, it can never be read back through the API, not even by the key that wrote it. That’s why secrets:set is separate from secrets:write: writing the value of a secret is a different operation from rotating one, and the platform won’t let you confuse them. The practical consequence: a key that injects secrets into a vault (CI, a deploy pipeline) gets secrets:set. A key that manages secret lifecycle (rotation, deletion) gets secrets:write or secrets:destructive. A key that only proxies through to a downstream service via the secret value gets secrets:read — which returns metadata and a proxy URL, never the value.

​

Minting a least-privilege key

​

API keys vs. OAuth — which to issue

The two credential types exist for different consumers; they aren’t interchangeable. The decision rule: if a person clicks a button to start the flow, OAuth. If a cron job or a CI runner starts it, API key.