API key scopes

Every Driftstack API key carries a set of scopes. Endpoints that declare a required scope allow the request only if the key’s scope set satisfies it. A few endpoints require no specific scope beyond a valid key — their docs pages say so explicitly (GET /v1/whoami is one).

You choose a key’s scopes when you create it in the Driftstack dashboard, where API keys are created, rotated and revoked.

Scope categories

There are three categories of scopes, in order of breadth:

1. Broad scopes — read, write, admin. Cover every resource of the corresponding verb across the customer’s account. The simplest mental model: “this key can do everything a customer can do at this verb level.”
2. Account-control scope — account_owner. Gates customer-account control.
3. Granular scopes — verb:resource syntax (e.g. read:sessions, write:webhooks). Narrow keys for integrations that should not have full account access.

Full scope list

Note — saved proxies are account-control too. Every route under /v1/account/me/proxies needs account_owner, listing included: a read + write key gets 403. That is GET and POST /v1/account/me/proxies, PUT and DELETE /v1/account/me/proxies/{id}, POST /v1/account/me/proxies/{id}/test, POST /v1/account/me/proxies/import, and the change-IP routes. Every agent session needs a proxy_id, so look the id up once with an account_owner key and give the job the id. See Find a proxy’s id.

Note — webhook management is an account-control operation. Creating, updating, deleting, or rotating webhook endpoints requires the account_owner scope, not a granular write:webhooks / admin:webhooks scope. Account-configuration surfaces are deliberately gated at the account-control level rather than at granular write level. (A broad admin key still satisfies account_owner through the legacy admin alias.)

Note — agent-session endpoints require the broad write scope. Session routes (/v1/sessions/*) accept the granular write:sessions, but the agent-session writes that start or drive a session (/v1/agent-sessions/* — create, message, steps, stop, close, reopen, resume, cookie import, history and file upload) gate on the broad write scope. There is no agent-sessions-specific granular scope. If you mint a narrow CI key, include the broad write scope to call these endpoints. Agent-session reads accept read:sessions. One documented agent-session write takes a granular scope: the profile notes (PUT /v1/agent-sessions/{id}/profile-notes) need write:profiles, because they edit the profile and run nothing. An OAuth token can hold only granular scopes, so OAuth apps can’t run AI sessions today; use an API key for that.

broad-satisfies-granular rule

A key with a broad scope satisfies any granular scope on the same verb:

• A key with read satisfies every read:* granular scope (read:sessions, read:profiles, read:webhooks, read:api-keys, read:billing, read:audit).
• A key with write satisfies any write:*.
• A key with admin (or account_owner) satisfies any admin:*.

The reverse is not true: a key with read:sessions does NOT satisfy read — narrow keys stay narrow. That’s the point of granular scoping; a read:sessions key can only ever read sessions, not profiles or webhooks.

key with: read              → can do: read, plus every read:* (read:sessions, read:profiles, read:webhooks, read:api-keys, read:billing, read:audit)
key with: read:sessions     → can do: read:sessions  (only)
key with: write             → can do: write, plus every write:* — but NO read:* (writes never imply reads)
key with: account_owner     → can do: read, write, plus any read:*/write:*/admin:*

What happens on a scope mismatch

The API returns HTTP 403 with an RFC 9457 problem-details body:

{
  "type": "https://errors.driftstack.dev/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This action requires the \"write:sessions\" scope."
}

The detail string names the exact scope required so you can mint a correctly-scoped replacement key (or extend the existing one).

Checking what your key actually has

GET /v1/whoami

Answers the other half of a scope mismatch — not what the route wanted, but what the key you are holding actually carries:

{
  "account_id": "acc_...",
  "api_key_id": "key_...",
  "tier": "pro_v3",
  "scopes": ["read", "write:sessions"]
}

Useful when a 403 is surprising: it confirms which key the request authenticated with, which matters when an environment has several configured.

Requires only a valid key, whatever its scopes, so any key can call it to see which scopes it has.

Picking scopes for a new key

When you create a key in the dashboard, you pick scopes per use case. Defaults:

• CI / test runner: read + write when it runs agent sessions (agent-session writes need the broad write). write:sessions writes only /v1/sessions; read:sessions still reads both kinds of session. The granular pair cannot read or manage webhooks, saved proxies or billing. read + write can read webhook endpoints, their deliveries and billing state. It cannot manage webhooks or list saved proxies (both need account_owner), and billing changes are made in the dashboard.
• Production application: read + write. Excludes account-management surfaces.
• AI automation job (agent sessions): read + write — agent-session writes need the broad write. Keep account_owner off the job key. That key cannot list your saved proxies, so look up the proxy_id once with an account_owner key and give the job the id. Store your Anthropic key or opt in to bundled billing once from the dashboard instead. See Run AI tasks from your code.
• Backup automation: read + read:audit.
• Webhook receiver: needs no API key. Driftstack signs each delivery with the endpoint’s whsec_ secret, so your receiver needs only that secret; see webhooks docs. A key you create in the dashboard must have at least one scope: an empty scope list is refused.
• Dashboard / customer self-service: account_owner. The default scope minted by the customer dashboard’s “first key” flow.