Scopes

A scope is a string that narrows what a credential can do. Scopes appear in two distinct contexts in Alter, and confusing them is the most common source of “why is this call failing 403.”

Scope kind	Lives on	Bounded by	Example
Provider scope	An OAuth credential and its grants	The OAuth provider’s scope vocabulary	https://www.googleapis.com/auth/calendar.readonly
Alter scope	An Alter API key	The Alter scope catalog	grants:read, agents:write

This page covers both.

Provider scopes

When a user completes the OAuth flow at Google, the consent screen lists the scopes the app is requesting. The user approves a specific set; Alter records that set with the credential and makes it available through the resulting grant. At call time, the provider checks the access token against the scope set and rejects the call if the route requires a scope the user did not grant.

Provider scopes are managed two places:

• Per-app default set — the operator picks the default scope set when configuring the provider in the developer portal. Users see this set on the consent screen.
• Per-session narrowing — the SDK can request a subset of the configured scopes for a Connect session via required_scopes (Python) or requiredScopes (TypeScript). Useful when one product surface needs read-only access and another needs read-write.

Scope mismatch handling: if the operator changes the configured scopes after users have already connected, existing credentials are marked for reevaluation. On the next SDK call, Alter clears that marker when the stored grant still covers the current requirement; otherwise the call raises ScopeReauthRequiredError. The same error can surface when a provider reports insufficient scope. The application must start a new Connect session and direct the user to its URL; the SDK does not open the prompt automatically.

Alter scopes

Alter API keys carry their own scope set, separate from any provider’s scopes. These are capability scopes on the Alter API itself — what the key is allowed to do against Alter’s own management surface:

The complete catalog below is generated from the backend’s current, versioned scope catalog and is the public source of truth.

Important AND-scope contracts:

• connect:initiate authorizes session creation, but OAuth Connect also requires grants:write and managed-secret delegation also requires secrets:write. Completing either flow creates a grant or delegation.
• tokens:retrieve authorizes direct SDK calls. Those calls report the provider outcome through audit:emit; without it, the provider call can still complete but its client-side outcome is not appended to the audit log.
• proxy:execute authorizes provider calls executed by the Alter backend. The backend records those outcomes itself.
• identity:resolve resolves verified identity contexts; identity:assert mints signed identity assertions. See Propagate identity to memory.

Catalog version: v13

Runtime API key scopes

These scopes are valid on app and agent runtime keys (alter_rk_… / alter_ak_…). They are rejected on Personal Access Tokens.

Scope	Kind
agents:admin	Resource permission
agents:read	Resource permission
agents:write	Resource permission
approvals:read	Resource permission
approvals:write	Resource permission
audit_logs:read	Resource permission
grants:admin	Resource permission
grants:read	Resource permission
grants:write	Resource permission
idp_users:read	Resource permission
idp_users:write	Resource permission
idps:admin	Resource permission
idps:read	Resource permission
idps:write	Resource permission
keys:admin	Resource permission
keys:read	Resource permission
keys:write	Resource permission
policies:admin	Resource permission
policies:read	Resource permission
policies:write	Resource permission
providers:admin	Resource permission
providers:read	Resource permission
providers:write	Resource permission
secrets:admin	Resource permission
secrets:read	Resource permission
secrets:write	Resource permission
usage:read	Resource permission
audit:emit	Action permission
connect:initiate	Action permission
identity:assert	Action permission
identity:resolve	Action permission
keys:derive	Action permission
proxy:execute	Action permission
spans:emit	Action permission
tokens:retrieve	Action permission

Personal Access Token scopes

These dashboard_* scopes are valid only on operator Personal Access Tokens (alter_pat_…). They are rejected on runtime keys.

Scope	Kind
dashboard_agents:admin	Dashboard permission
dashboard_agents:read	Dashboard permission
dashboard_agents:write	Dashboard permission
dashboard_analytics:read	Dashboard permission
dashboard_app_policy:read	Dashboard permission
dashboard_app_policy:rules_create	Dashboard permission
dashboard_app_policy:rules_delete	Dashboard permission
dashboard_app_policy:rules_update	Dashboard permission
dashboard_approvals:read	Dashboard permission
dashboard_apps:admin	Dashboard permission
dashboard_apps:delete	Dashboard permission
dashboard_apps:read	Dashboard permission
dashboard_apps:write	Dashboard permission
dashboard_audit:read	Dashboard permission
dashboard_branding:read	Dashboard permission
dashboard_branding:write	Dashboard permission
dashboard_end_users:read	Dashboard permission
dashboard_grants:admin	Dashboard permission
dashboard_grants:read	Dashboard permission
dashboard_identity_providers:create	Dashboard permission
dashboard_identity_providers:webhooks	Dashboard permission
dashboard_keys:admin	Dashboard permission
dashboard_keys:read	Dashboard permission
dashboard_keys:write	Dashboard permission
dashboard_pats:read	Dashboard permission
dashboard_providers:admin	Dashboard permission
dashboard_providers:delete	Dashboard permission
dashboard_providers:read	Dashboard permission
dashboard_providers:write	Dashboard permission
dashboard_secrets:admin	Dashboard permission
dashboard_secrets:delete	Dashboard permission
dashboard_secrets:read	Dashboard permission
dashboard_secrets:write	Dashboard permission

Every app-level key is minted with an explicit scope set. Managed-agent keys receive a bounded runtime set rather than a wildcard, and derived keys can narrow their parent’s scopes further — an agent that only needs to issue provider calls does not need permission to create other agents.

Attenuation

with_constraints(scopes=[...]) returns a sibling SDK instance whose narrowed scopes are surfaced through the SDK on every request. The constraint is the intersection of the key’s scopes and the supplied list — it can only narrow, never broaden. Useful for handing a derived SDK instance to a less-trusted component (a plugin, a tool call) without minting a new key. The same call also accepts an optional rule — a request rule, evaluated server-side, carried by every request the returned instance makes, that can only further restrict each one; pass scopes, rule, or both.

If the route requires a scope not in the intersection, the backend raises InsufficientScopeError with the missing scope listed.

What’s next

• Errors — ScopeReauthRequiredError, InsufficientScopeError.
• API keys — minting keys with specific scope sets.
• Connections — where provider scopes are first established.