Authentication

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

$
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.

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:

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

Configuration & integrations

Smart QA & consortium

Data deletion (irreversible)

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:

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:

1
{
2
  "error": "unauthorized",
3
  "detail": "Invalid or missing API key.",
4
  "status_code": 401
5
}

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 ”):

1
{
2
  "detail": "API key missing required scope: redact:write or sessions:write"
3
}

Related

• Errors — Full error response reference including 401 and 403
• Rate Limiting — Plan-based rate limits per key
• JavaScript SDK — Embedding the verification flow with verifa.js