Create an API key

API keys authenticate requests to the public API. Each key is bound to one region and one mode — see Modes and regions.

Before you start

You need an organization membership and an active mode (test or live) selected in the sidebar. Keys you create reflect the active mode.

Create a key

Open Developers → API keys and click New API key. Pick a key type:

• Secret key (ah_sk_…) — server-to-server. Carries scopes. Keep private.
• Publishable key (ah_pk_…) — browser-side SDK. Bound to one or more origins; does not carry scopes.

Give the key a label that identifies where it runs (for example production-api). Pick an expiration if you want the key to auto-revoke. For publishable keys, list every allowed origin (one per line); bare * is rejected.

The key is shown once and is then unrecoverable. Copy it into a secrets manager before closing the dialog.

Scopes

Secret keys carry a list of scopes, grouped below by what they control. Grant the minimum your integration needs. For common integration patterns, see Choosing scopes for your key.

Verification

Scope	Grants
applicants:read	Read applicants. Read applicant records, including their full personal information. Sensitive: Returns the applicant's full personal information.
applicants:write	Manage applicants. Create and update applicant records.
sessions:read	Read sessions. Read verification sessions and their results.
sessions:write	Manage sessions. Create verification sessions and manage their lifecycle: cancel, resend the invite, reset a used link, add notes, and skip a required step. Sensitive: Includes skipping a required verification step, which can complete a session with missing evidence. Grant only to keys that need full control of a session.
idv:write	Scan ID documents. Run a standalone ID document scan without a verification session.

Session tokens

Scope	Grants
sessions:browser_token	Mint browser tokens. Mint a short-lived token to start a verification in the applicant's browser.
sessions:workspace_token	Mint workspace tokens. Mint a token for reviewer workspace tooling.

Reports

Scope	Grants
sessions:read_report	Download reports. Download the full-evidence verification report as a PDF. Sensitive: The report contains the applicant's full verification evidence.

Adjudication

Scope	Grants
sessions:review	Review sessions. Approve or decline a verification session.

Configuration

Scope	Grants
workflow-templates:read	Read workflow templates. Read verification workflow templates.
workflow-templates:write	Manage workflow templates. Create and update verification workflow templates.
links:read	Read links. Read shareable verification links.
links:write	Manage links. Create and update shareable verification links.

Compliance & billing

Scope	Grants
dsar:create	Submit data requests. Submit a data subject access or erasure request for an applicant. Sensitive: Acts on the applicant's personal data to satisfy a data subject request.
billing:read	Read billing. Read wallet balance, credit grants, transactions, and usage tiers.

A call without the required scope returns insufficient_scope (HTTP 403) and names the missing scope in the response. See the API error codes.

Store the key

Treat the key like a password. Store it in a secrets manager (for example, 1Password) and never commit it. We can only display the key once at creation. If you lose it, rotate it.

Use the key in a request

Send the key in the Authorization header against the endpoint that matches the region:

curl -i https://api-dev.us.autohost-dev.uk/v1/me \
  -H "Authorization: Bearer ah_sk_us_test_<your-key>"

Every response includes an X-Request-Id header. Capture it in your logs — support tickets that include the request ID get triaged faster.

Troubleshooting

See Why was my API key rejected?. Common causes: region mismatch, missing scope, or the key has been revoked. To cycle a key out, see Rotate or revoke an API key.