Choosing scopes for your key

Every secret key carries a list of scopes. The full catalog, grouped and described, is in Create an API key. 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.

`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).

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).
• sessions:workspace_token: mint a token to embed the hosted review workspace in your product (see Embed the review workspace).

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.