Scopes & permissions

A key's scopes are catalog permission keys — the same permissions the app's roles are built from. A request succeeds only when the key holds the permission the operation requires.

Each operation publishes its required permission

In the OpenAPI document, every operation carries an x-required-permission vendor extension naming the catalog permission it enforces at runtime. The security scheme is bearerAuth (your sk_live_… token). Read it straight from the spec:

curl https://your-app.example.com/api/v1/openapi.json \
  | jq '.paths["/customers"].get["x-required-permission"]'

If a key is otherwise valid but lacks the required permission, the request returns 403 with the forbidden envelope (see Errors).

A key can never out-scope its creator

Scopes are bounded twice when a key is created:

• Eligible scopes only. Only permissions on the API-key eligibility allowlist may be granted to a key at all. Sensitive surfaces (for example, managing API keys themselves) are session-only and can never be granted to a key.
• Creator-bounding. Every requested scope must be a permission the human creating the key actually holds. A key can never escalate beyond its creator's own permissions.