> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Authentication

> API key management, scopes, and security best practices.

All API requests are authenticated using API keys passed in the `X-API-Key`
header.

```bash
curl https://api.withverifa.com/api/v1/sessions \
  -H "X-API-Key: vk_live_your_key_here"
```

## Key types

Verifa supports two types of API keys:

### Secret keys (default)

Secret keys are used for server-side API calls. They have full access to your
configured scopes and should **never be exposed in client-side code**.

| Environment | Prefix        | Example                      |
| ----------- | ------------- | ---------------------------- |
| Production  | `vk_live_`    | `vk_live_abc123def456...`    |
| Sandbox     | `vk_sandbox_` | `vk_sandbox_abc123def456...` |

A sandbox key can only access sandbox resources, and a live key can only access
live resources.

## Scopes

Each API key is granted a set of scopes that control which endpoints it can
access. Scopes follow the `resource:action` pattern.

### Default scopes

These scopes are granted to all new API keys at creation time:

| Scope                | Description                                    |
| -------------------- | ---------------------------------------------- |
| `sessions:read`      | View and list verification sessions            |
| `sessions:create`    | Create verification sessions                   |
| `sessions:write`     | Update, expire, resume, and reprocess sessions |
| `verifications:read` | View verification results and documents        |
| `documents:read`     | View and list documents                        |
| `documents:write`    | Upload documents to a session                  |
| `screening:read`     | View screening records and hits                |
| `screening:write`    | Trigger AML rescreens                          |
| `checks:read`        | View screening checks and hits                 |
| `checks:write`       | Create, re-run, and tag screening checks       |
| `identities:read`    | View verified identity records                 |
| `workflows:read`     | View workflows and workflow runs               |

### Opt-in scopes

These scopes must be explicitly added when creating or editing an API
key. They're not granted by default. The "Provision an API key" deep-link
on the **AI Integrations** dashboard page can pre-fill the right set for
a given MCP connection.

#### Identity, case, and screening operations

| Scope                        | Description                                                        |
| ---------------------------- | ------------------------------------------------------------------ |
| `sessions:external-decision` | Submit external-gate decisions for paused workflows                |
| `identities:write`           | Tag identities, manage blocklist entries, modify identity metadata |
| `cases:read`                 | View and list review cases                                         |
| `cases:write`                | Claim, release, assign, and comment on review cases                |
| `cases:decide`               | Approve, reject, or escalate a review case                         |
| `review:write`               | Correct extracted PII on a case under review                       |
| `workflows:write`            | Create, update, and manage workflows                               |
| `workflows:trigger`          | Re-run a workflow on an existing session                           |

#### Configuration & integrations

| Scope                | Description                                                                                                             |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `settings:write`     | Manage identity types, relationship types, document types, document groups, document fingerprints, custom-field schemas |
| `integrations:read`  | View third-party integrations (Slack, Teams, Salesforce, ServiceNow, Asana, Monday)                                     |
| `integrations:write` | Connect, configure, test, and disconnect third-party integrations                                                       |
| `webhooks:read`      | View webhook endpoints and recent deliveries                                                                            |
| `webhooks:write`     | Create, update, and archive webhook endpoints                                                                           |
| `api_keys:read`      | View this organization's API keys (metadata only)                                                                       |
| `api_keys:write`     | Create, update, and revoke API keys                                                                                     |
| `audit_logs:read`    | Access the organization audit log                                                                                       |

#### Smart QA & consortium

| Scope               | Description                                          |
| ------------------- | ---------------------------------------------------- |
| `audit:read`        | View Smart QA audit findings and statistics          |
| `audit:write`       | Acknowledge and dismiss audit findings               |
| `consortium:read`   | View consortium memberships and cross-org matches    |
| `consortium:write`  | Investigate and resolve consortium matches           |
| `consortium:manage` | Change this organization's consortium sharing policy |

#### Data deletion (irreversible)

| Scope          | Description                                                                                                                                                                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `redact:write` | Permanently delete personal data (GDPR Art. 17): redact sessions, identities, checks; delete blocklist rows. **Irreversible.** Never granted by default and never available on publishable keys. Required to invoke any MCP destructive tool. |

### Backward compatibility

Several endpoints accept either the new specific scope or the older
broad scope it was split from. Keys minted before the scope split keep
working unchanged, and integrations can migrate at their own pace. A
non-exhaustive list:

| Endpoint                                                                                                                                       | Accepted scopes (any one)                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `DELETE /sessions/{id}/data`                                                                                                                   | `redact:write` OR `sessions:write`                    |
| `POST /sessions/bulk-redact`                                                                                                                   | `redact:write` OR `sessions:write`                    |
| `DELETE /identities/{id}/data`                                                                                                                 | `redact:write` OR `identities:write`                  |
| `POST /checks/{id}/redact`                                                                                                                     | `redact:write` OR `checks:write` OR `screening:write` |
| `DELETE /documents/{id}` (GDPR redact)                                                                                                         | `redact:write` OR `documents:write`                   |
| `DELETE /blocklist/{id}`                                                                                                                       | `redact:write` OR `identities:write`                  |
| `POST /cases/{id}/approve\|reject\|escalate`                                                                                                   | `cases:decide` OR `cases:write`                       |
| `POST /workflows/{id}/trigger`                                                                                                                 | `workflows:trigger` OR `workflows:write`              |
| `POST/PATCH/DELETE /identity-types`, `/relationship-types`, `/document-types`, `/document-groups`, custom-field schemas, document fingerprints | `settings:write` OR the per-resource `:write`         |

We recommend pinning new keys to the **specific** scope rather than the
broad one, so future endpoint additions don't quietly inherit access.

## Security best practices

* **Never expose secret keys in client-side code.** Keep secret keys on your server.
* **Use separate keys for sandbox and production.** This prevents test data from
  mixing with live verifications.
* **Rotate keys periodically.** Create a new key, migrate your integration, then
  revoke the old key.
* **Use the minimum scopes required.** Only grant management scopes to keys that
  need them.

## Dashboard session refresh

Dashboard sessions are cookie-based (`vk_org_token`, 8h). The dashboard
extends an active session by calling:

```
POST /api/v1/auth/refresh
```

This endpoint is used internally by the dashboard SPA and isn't required for
server-to-server API access (which uses `X-API-Key`).

## SAML IdP-initiated sign-in

SAML SP-initiated sign-in (the user starts at Verifa and is redirected to
their IdP) is enabled by default for SSO-configured organizations.

SAML **IdP-initiated** sign-in (the user launches Verifa from an Okta or
Azure AD tile) is **opt-in per organization** and disabled by default.
Contact support to enable it for your org.

## IP allowlisting

For additional security, you can restrict API key usage to specific IP addresses
or CIDR ranges. Contact support to configure IP allowlisting for your
organization.

## Error responses

If the API key is missing or invalid, the API returns `401 Unauthorized`:

```json
{
  "error": "unauthorized",
  "detail": "Invalid or missing API key.",
  "status_code": 401
}
```

If the key lacks the required scope for an endpoint, the API returns
`403 Forbidden`. The detail names every scope that would have allowed
the call (multiple scopes are joined with " or "):

```json
{
  "detail": "API key missing required scope: redact:write or sessions:write"
}
```

## Related

* [Errors](/api-details/errors) — Full error response reference including 401 and 403
* [Rate Limiting](/api-details/rate-limiting) — Plan-based rate limits per key
* [JavaScript SDK](/integration-guides/java-script-sdk) — Embedding the verification flow with verifa.js