Authentication

Overview

CAIRL's partner API uses API keys for server-to-server authentication. Every API key is scoped to a single partner account and can operate in either test or live mode.

The recommended progression is:

Run Sandbox with no credentials. Sandbox recipes are synthetic and never create billable VAEs, wallet debits, enrollments, or production claims.
Generate cairl_test_* credentials when you are ready to call CAIRL from your own application or CI.
Use cairl_live_* credentials only after production gates and wallet readiness are complete.

Authorization: Bearer cairl_live_...

Key types

Mode	Prefix	Usage
Test	`cairl_test_...`	Development and CI. No real identity verification. Mock claims returned. Capped at 100 calls/day.
Live	`cairl_live_...`	Production. Real verification. Wallet balance required.

Test and live keys share the same API surface — switching to production requires only a key swap.

Obtaining API keys

Create a partner account at cairl.app/register
Run your first Checkbox, OAuth, or Connect recipe in Sandbox
Navigate to Dashboard → API Keys when you need test credentials
Click Generate Key
Copy and store the key value — it is shown once and cannot be retrieved again

If you lose a key, revoke it and generate a new one. Revocation is immediate.

Using your key

Include the key in every request as a Bearer token:

curl https://cairl.app/api/verify/hvf-session/{session_id} \
  -H "Authorization: Bearer cairl_live_YOUR_KEY_HERE"

const response = await fetch(
  "https://cairl.app/api/verify/hvf-session/" + sessionId,
  {
    headers: {
      Authorization: `Bearer ${process.env.CAIRL_API_KEY}`,
    },
  },
);

Key security

Store keys in environment variables, never in source code
Use separate keys for staging and production environments
Rotate keys periodically via the dashboard Rotate Secret button
Revoke compromised keys immediately from Dashboard → API Keys

OAuth flow credentials

The OAuth hosted verification flow uses a separate credential pair:

Credential	Usage
`client_id`	Your API key value — passed in the authorization URL as `client_id`
`client_secret`	Your key's associated secret — used at the token exchange step

See the Quickstart for the complete OAuth flow.

Test mode behavior

When using a test key:

The CAIRL verification flow runs in sandbox mode (mocked document/face checks)
Token exchange returns mock claims (age_18_plus: true, identity_verified: true)
No wallet balance is required and no billing events are recorded
The sub returned is always a test-prefixed pseudonymous identifier

Test mode is indistinguishable from live mode at the API level — all endpoints, response shapes, and error codes are identical.

Sandbox recipes are earlier than test mode. They demonstrate the product flow inside CAIRL, show synthetic outputs, and do not expose or require any API key.