Glossary

Short definitions of the terms you will meet in the integration docs, in the order you are likely to meet them.

Business facet

Your site's presence inside CAIRL. You create one at /home/facets/new?type=business, and every integration setting — keys, callback URLs, funds, webhooks — lives under it at /home/f/{slug}/..., where {slug} is the short name CAIRL assigns (for example b-yoursite). One CAIRL account can hold several business facets, one per site.

Authorization entry (/oauth/authorize)

The "Sign in with CAIRL" door. It signs the user in, checks whether their existing CAIRL verification meets your key's required depth and falls inside its time-based freshness window, and goes straight to the consent screen when it does; only a user who falls short is sent through verification. Takes the same parameters as /verify/start plus response_type=code.

The freshness half covers the time-based policies only — daily, 3day, weekly, biweekly, monthly. The event-driven policies, session and transaction, are not enforced at this door today.

HVF (hosted verification flow)

The CAIRL-hosted pages a user goes through after your site redirects them to https://cairl.app/verify/start: sign in or create a CAIRL account, verify identity, and approve sharing claims with your site. You do not build any of it. A single pass through it is a verification session, which expires after 30 minutes.

Re-verification is skipped by entry point, not by history. On a live key every request to /verify/start performs a new verification, however recently the person verified — only re-entering the same still-live session resumes one. The door that honours an existing verification is /oauth/authorize, above.

On a test or sandbox credential none of that happens: /verify/start/check-verification returns nextStep: "synthetic_claims" before the real verification engine is mounted, so there is no document processing and no liveness check. A sandbox run therefore exercises the plumbing, never the capture pipeline.

Scope vs. claim

A scope is what you ask for; a claim is what you get back.

• Scopes go in the scope parameter of the authorization URL and use colons and, for ages, a plus sign: age:18+, identity:verified, freshness:current.
• Claims come back in the claims object of the userinfo response and use underscores: age_18_plus, identity_verified, freshness_current.

They are spelled differently on purpose. Sending a claim name as a scope is rejected with invalid_scope. The full mapping is in the claims reference.

sub (pairwise ID)

The identifier for a user in the token and userinfo responses, for example pws_v1_abc123. It is pairwise: the same person gets the same sub on your site every time, and a different sub on every other site that integrates CAIRL. Use it as the key for recognising returning users. It contains no name and cannot be turned back into one, but it is still personal data and should be stored with the same care as an email address. Test credentials return a random pws_v1_test_… value instead, which is not pairwise and should not be used to link sessions.

Test vs. live credentials

Both are generated on /home/f/{slug}/keys and look like cairl_test_... and cairl_live_....

• Test credentials need no funds and accept http://localhost callback URLs. They run the real flow — you sign in with your own CAIRL account and see the consent screen — but return fixture claims for the requested scopes, a random pws_v1_test_… sub, and no billing. You do not need to complete identity verification to use them. Use them to build and check the plumbing; the full list is in what is real and what is synthetic in test mode.
• Live credentials require a loaded balance ($50 minimum), https:// callback URLs, and a chosen set of Required Claims. They run real verification and are billed per Verified Access Event.

The API is identical for both; switching is a credential swap.

Callback (redirect) URL

The address on your site that CAIRL sends the user back to when the hosted flow finishes, carrying code and state (or error). You register it on /home/f/{slug}/connect and send the same value as redirect_uri in every authorization request. The two must match character for character, and the URL may not contain a query string, # fragment, or wildcard.

PKCE

"Proof Key for Code Exchange" — a small extra step in the OAuth flow that CAIRL requires. Before redirecting, your server makes a random secret (the code_verifier) and sends only its SHA-256 hash (the code_challenge). When exchanging the code, it sends the original code_verifier. This proves that the server finishing the flow is the one that started it, so an intercepted code is useless on its own. The quickstart has the three-line implementation.

state

A random value (at least 16 characters) your server generates before redirecting and checks when the user comes back. If the value in the callback does not match the one you stored, discard the callback. This is the protection against forged callbacks (CSRF).

VAE (Verified Access Event)

The billable unit. A VAE is recorded when your server successfully exchanges an authorization code for a token for a user who is already enrolled with your site. A user's very first successful exchange on your site is an enrollment instead, billed at its own rate. Abandoned flows, failed verifications, and failed exchanges are not VAEs and are not billed; test credentials are not billed at all.

Funds (prepaid balance)

Live usage is paid from a prepaid balance you load at /home/f/{slug}/billing (Add Funds, $50 minimum). Enrollments and VAEs are deducted from it at token exchange. If the balance is insufficient, the token endpoint returns 402 payment_required and no token is issued. Older docs and some dashboard copy call this balance the wallet.

Consent screen

The page in the hosted flow where CAIRL shows the user your site's name and the exact claims you requested, and lists what is not shared (name, address, date of birth, ID document or photos, email, phone). The user approves or declines. Shown with test and live credentials alike; consent given in test mode is real consent and is remembered for the same site and scopes.

Freshness

How recent a user's verification must be to count. You pick a Freshness Policy per key (daily, weekly, monthly, quarterly, annual) and request freshness:current; the freshness_current claim is false when the last verification is older than that window.

Userinfo snapshot

The claims returned by /api/oauth/userinfo are the values as they were when the token was issued (evaluated_at), not a live re-check. To get current values, run the flow again and get a new token.

Webhook

An HTTPS endpoint on your side that CAIRL POSTs signed event notifications to (session completed, session failed, enrollment created, VAE resolved). Configured per key on /home/f/{slug}/keys; optional.

Sandbox

A keyless, synthetic demo of the flow at /home/developer/sandbox, when it is available in your environment. It creates no sessions, enrollments, or charges. It is not required for any integration step; test credentials are the first real step.