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.

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
Navigate to Dashboard → API Keys
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.