import { Aside } from '@astrojs/starlight/components';

Every secret key carries a list of scopes. The full catalog, grouped and described, is in [Create an API key](/developers/api-keys#scopes). This page covers which scopes fit common integration patterns.

## Read-only auditor

An integration that only needs to read data, never create or modify it (a reporting pipeline, a data warehouse sync, an internal dashboard), should carry only the `:read` scopes it actually queries:

- `applicants:read`
- `sessions:read`
- `workflow-templates:read`
- `links:read`
- `billing:read`

None of these can create, modify, cancel, or decide anything. A leaked read-only key can disclose data but cannot mutate it.

## Run verifications

An integration that creates applicants and starts verifications, and manages them afterward (resend an invite, cancel, add a note, skip a step), needs both the read and write session scopes:

- `applicants:read`
- `applicants:write`
- `sessions:read`
- `sessions:write`

Add `idv:write` only if you also call the standalone ID document scan endpoint outside of a verification session.

<Aside type="caution" title="`sessions:write` is broad">
  `sessions:write` is a single scope that covers session creation **and** every session lifecycle action: cancel, resend the invite, reset a used link, add a note, and skip a required verification step. A key that carries it can skip a step on every session in the key's own mode and region, which can complete a verification with missing evidence. There is no narrower scope that grants create without also granting these lifecycle actions.

  Because the scope can't be split further, keep the blast radius small at the key level instead: give the key a label that identifies exactly where it runs, set an expiration instead of a never-expiring key, and watch its last-used timestamp in **Developers → API keys** so unexpected use stands out. If a key carrying `sessions:write` may have leaked, rotate it immediately (see [Rotate or revoke an API key](/developers/api-keys-rotate)).
</Aside>

## Compliance reviewer

An integration that reviews and decides on verifications, without creating or modifying them, adds `sessions:review` to the read-only set:

- `applicants:read`
- `sessions:read`
- `workflow-templates:read`
- `links:read`
- `billing:read`
- `sessions:review`

This lets the integration approve or decline a session without being able to create, cancel, or skip a step on one.

## Browser and workspace tokens

An integration that mints short-lived tokens for its own frontend, rather than calling the REST API with the secret key directly, needs only the mint scopes:

- `sessions:browser_token`: mint a token so the applicant's own browser can run the verification (see [Token handoff](/developers/sdks/token-handoff)).
- `sessions:workspace_token`: mint a token to embed the hosted review workspace in your product (see [Embed the review workspace](/developers/sdks/workspace-reviewer)).

These two scopes only authorize minting; they do not grant read or write access to session data on their own. Pair them with the scopes above that match what your backend does directly with the REST API.

## Compliance & billing

`dsar:create` submits a data subject access or erasure request on an applicant's behalf and should be limited to the integration that actually handles those requests, since it acts on personal data. `billing:read` is safe to include in any read-only key.