Authentication

How to authenticate with the CAIRL API using API keys and OAuth client credentials.

Overview

CAIRL's integration API uses API keys for server-to-server authentication. Every API key belongs to one business facet and operates in either test or live mode.

The recommended progression is:

Build against the cairl_test_* credentials CAIRL creates with your business facet. Test credentials need no funds, run the real sign-in and consent flow, and return fixture claims in place of verification results (see Test mode behavior).
Load funds, register a live https:// callback URL, then click Create live credentials for cairl_live_* credentials.

Authorization: Bearer cairl_live_...

If a keyless Sandbox page is available in your environment at /home/developer/sandbox, it shows a synthetic run of the flow without any credentials. It is optional.

Key types

Mode	Prefix	Usage
Test	`cairl_test_...`	Development and CI. Real sign-in and consent screen; fixture claims in place of verification results; no billing. 100 calls/day.
Live	`cairl_live_...`	Production. Real verification. Loaded balance required ($50 minimum).

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

Obtaining API keys

Create a CAIRL account at cairl.app/register
Add your website as a business facet at /home/facets/new?type=business and choose Business mode (My website or app) and Organization type; the form requires both (also editable later at /home/f/{slug}/config). This unlocks the API Keys and Connect pages.
Creating the facet creates your test credentials. Copy the client ID and client secret from the Your test credentials card on /home/f/{slug}/integrate, then click I've saved these. The secret is shown once; CAIRL stores only a fingerprint of it. If you dismissed the card before saving, generate new credentials on /home/f/{slug}/keys, where the pair created with the facet is labelled Default test credentials.
For live credentials, load funds at /home/f/{slug}/billing and register a live https:// callback URL. /home/f/{slug}/keys then offers Create live credentials: one click, shown once in the same reveal dialog. Live credentials are created only when you click.
To create any further key by hand, click + Generate Key on /home/f/{slug}/keys, enter a label, choose Mode (Test or Live), and for live keys select the Required Claims the key may request. The client ID and secret are shown once and cannot be retrieved again.

If you lose a secret, revoke the key 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, not in source code
Use separate keys for staging and production environments
To replace an API key or client secret, generate a new key on /home/f/{slug}/keys, deploy it, then revoke the old one. The Rotate Secret button on that page rotates only the webhook signing secret, not the API key or client secret.
Revoke compromised keys immediately from /home/f/{slug}/keys

OAuth flow credentials

The OAuth hosted verification flow uses the key pair generated above:

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.

A test key runs the same OAuth path as a live key. Whoever runs the test signs in with their own CAIRL account (password manager, MFA and all), sees the real consent screen naming your site and the claims you requested, and is sent back to your callback with a code. Test mode changes two things only: the claims are fixture values rather than verification results, and nothing is billed.

Use your own CAIRL account to test. You do not need to complete identity verification first: in test mode the key's verification depth and freshness requirements are treated as satisfied, and fixture claims are returned for the scopes you requested.

What is real and what is synthetic in test mode

Real — same as live	Synthetic — test only
Your sign-in to CAIRL, including MFA if your account has it on	Claim values: fixture claims filtered to the scopes you requested, not verification results
The consent screen naming your site and the requested claims	`sub`: a random `pws_v1_test_…` value, different from the pairwise `sub` a live key returns
The callback to your `redirect_uri` with `code` and `state`	Billing: no enrollment, no Verified Access Event, no balance debit
The code exchange and the access token	Verification depth and freshness: treated as satisfied, so a tester who has not verified still gets claims
The userinfo response shape
`verification.session.completed` webhooks, marked `"mode": "test"`

Other details of test mode:

The access token and the userinfo response carry "mode": "test" (live keys return "mode": "live"), so your code can tell the two apart.
Consent given in test mode is real consent. It creates a connection between the tester's CAIRL account and your site, so a later live authorization for the same site and scopes does not prompt again.
Because the test sub is random, do not use it to link test sessions to each other or to real users.
http://localhost callback URLs are accepted.
If the key has a non-empty Required Claims list, the scopes you request must be within that list, the same rule as for live keys. With an empty list, any wire scope may be requested.
No balance is required and no billing events are recorded.

Test mode matches live mode at the API level — endpoints, response shapes, and error codes are identical.

Authentication

On this page