API authentication

API keys, session tokens and how to send them.

#Secret API keys

Create keys in Developers → API keys. Only users with the admin or developer role can manage them. Keys are stored hashed, so the full key is shown once.

Send the key in either header. Both work on every /v1 and /v3 endpoint:

curl https://{{HOST}}/v3/sessions/ -H "x-api-key: sk_live_..."
curl https://{{HOST}}/v1/verifications -H "Authorization: Bearer sk_live_..."

#Session tokens

A session token (vs_…) is limited to one verification and expires after one hour. It is safe to give to a browser or app, because it can only upload and submit that user's data. Use it with the hosted flow, the web SDK or the client flow API. Get a fresh one with POST /v1/verifications/{id}/session.

#Rotating keys

Create the new key, deploy it, then delete the old key in the console. Deleting takes effect straight away.

#Rate limits

Limits depend on your plan. When you go over, the API answers 429 with { "error": { "code": "rate_limited" } }. Back off and retry.

#Errors

Every error uses the same shape:

{ "error": { "code": "invalid_request", "message": "workflow_id not found" } }