Authentication | Verifa

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.

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

Publishable keys

Publishable keys are designed for use in frontend code (browsers, SPAs, mobile webviews). They can only create verification sessions — they cannot read results, access PII, or manage resources.

Environment	Prefix	Example
Production	`vk_pub_live_`	`vk_pub_live_abc123def456...`
Sandbox	`vk_pub_sandbox_`	`vk_pub_sandbox_abc123def456...`

Publishable keys are safe to embed in JavaScript because:

They can only call POST /api/v1/sessions (scope: sessions:create)
Session creation responses contain no sensitive data
Result retrieval requires a secret key on your server
They have a stricter rate limit (10 requests/minute)
You can optionally restrict them to specific origins (domains)

Use publishable keys with the verifa.js SDK for the simplest possible frontend integration.

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:

Scope	Description
`sessions:read`	List and retrieve sessions
`sessions:create`	Create verification sessions
`sessions:write`	Expire, redact, update, and reprocess sessions
`verifications:read`	Retrieve verification results and documents
`identities:read`	List and retrieve verified identities

Management scopes

These scopes must be explicitly granted and are intended for administrative integrations:

Scope	Description
`webhooks:read`	List webhook endpoints
`webhooks:write`	Create, update, and delete webhook endpoints
`keys:read`	List API keys
`keys:write`	Create and revoke API keys
`org:read`	Read organization settings
`org:write`	Update organization settings
`screening:read`	Access watchlist screening records
`screening:write`	Trigger AML screens and manage monitoring
`workflows:read`	List and retrieve workflows
`workflows:write`	Create, update, and trigger workflow runs
`cases:read`	List and retrieve review cases
`cases:write`	Approve, reject, escalate, and manage cases
`lists:read`	List and retrieve custom screening lists
`lists:write`	Create, update, and manage custom lists
`documents:write`	Upload documents to sessions
`audit:read`	Access audit findings and statistics
`analytics:read`	Access verification analytics

Security best practices

Never expose secret keys in client-side code. Use publishable keys (vk_pub_*) for frontend integrations and 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.
Set allowed origins on publishable keys. Restrict which domains can use your publishable key to prevent unauthorized usage.

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:

1 {
2   "error": "forbidden",
3   "detail": "API key does not have the required scope: webhooks:write",
4   "status_code": 403
5 }

Errors — Full error response reference including 401 and 403
Rate Limiting — Plan-based rate limits per key
JavaScript SDK — Using publishable keys with verifa.js