API keys

Customer API keys are how code authenticates to Driftstack on a paid tier, including any Manual tier. Each key carries a fixed scope set; pick the narrowest scope that fits the integration's purpose.

Free uses browser sign-in in the desktop app. That flow stores a restricted ds_test_… device credential automatically; it is not a customer API key, a general SDK key, or a sandbox credential.

Minting a key

On a paid tier, open the dashboard → Settings → API keys → Create. You'll see the full plaintext key once — copy it now and store it in your config / secret manager. We only store the hash; if you lose the plaintext, revoke and mint a new one.

Customer-key format: ds_live_<random>. The ds_live_ prefix is how Driftstack detects "this looks like an API key" during request parsing.

A Free dashboard web session can list and revoke keys retained from before a downgrade, but create and rotate return an RFC 9457 403 Forbidden. Existing ordinary keys are rejected while the account is Free and work again after an upgrade unless revoked or expired.

Scopes

Each key carries one or more scopes. Driftstack offers two shapes:

Broad scopes (most common)

Scope	Grants
`read`	Read sessions and profiles.
`write`	Mutate sessions and profiles. Does NOT include billing.
`account_owner`	Read-write across the whole account, including billing and team management.

Granular scopes (verb:resource)

For tighter least-privilege integrations:

Scope	Grants
`read:sessions`	Read session metadata + history.
`write:sessions`	Start + stop sessions.
`read:profiles`	Read browser-profile metadata.
`write:profiles`	Mutate profiles.
`admin:profiles`	Reserved — no route enforces it; profile writes use write:profiles.
`read:webhooks`	List webhook endpoints + delivery history.
`write:webhooks`	Reserved — endpoint management requires account_owner.
`admin:webhooks`	Reserved — secret rotation and deletion require account_owner.
`read:api-keys`	List the account's API keys (metadata only).
`admin:api-keys`	Reserved — minting and revoking require account_owner.
`read:billing`	Read invoices, usage, and crypto-order history.
`admin:billing`	Initiate checkout sessions + manage subscriptions.
`read:audit`	Read the account audit log.

Broad scopes satisfy the corresponding granular scopes on the same verb. A key with read can call any endpoint that requires read:sessions, but a key with only read:sessions cannot call endpoints that require read:profiles.

Using a key

On an API-enabled paid tier, use bearer-token auth:

Authorization: Bearer ds_live_…

Every authenticated response carries rate-limit headers (see /docs/rate-limits). Watch them; they'll save you a 429 down the line.

Rotating a key

Routine hygiene: rotate any production key at least every 90 days. The flow:

Mint a new key with the same scope set as the old one.
Deploy the new key to your environment.
Verify your production traffic is using the new key. The API Keys page shows each key's last_used_at, so you can confirm the successor is active and the old key has stopped advancing.
Revoke the old key from the dashboard.

If a key leaks

Immediately revoke the key from the dashboard. Effects:

Subsequent requests with that key return 401.
Any in-flight session it started keeps running (sessions are tied to the account, not the key). Stop the session explicitly if you need it gone.
The revocation is logged in your account audit log with the actor + timestamp.

Email [email protected] if the leak resulted in unauthorized activity — we'll help audit the account.

How many keys should I have?

One key per environment (production, staging, dev). Makes rotation + revocation surgical.
One key per third-party integration if you're handing keys to other services. Revoking one integration doesn't take out the others.
Don't share keys across team members. Humans should use their own dashboard account. Use OAuth when an approved third-party application needs delegated customer access.

API key metadata in audit logs

An API-key-authenticated audit entry carries the acting actor_key_id. Dashboard-session and system entries can carry actor_key_id: null; the public field is not named api_key_id. View the audit log in the dashboard or via GET /v1/account/audit-log.

FAQ

Can I view a key's plaintext after creation?: No. We only store the hash; the plaintext is shown once on creation. If you lost it, revoke and mint a new one.
What happens if I use the same key from two regions simultaneously?: Fine — keys aren't bound to a region. Rate limits are per-account, so the two regions share the bucket budget.
Can I scope a key to a specific session id?: No. API-key authorization uses verb:resource scopes (e.g. read:sessions).

Support

Email [email protected].