Getting Started

This guide walks your business through the fastest path to a working CAIRL integration: set up your account, copy the test credentials CAIRL creates for you, run the flow end to end, then create live credentials once you are ready to be billed.

You do not need to be a developer to follow Step 0. Steps 1 through 5 involve a small amount of server-side code; if your site is built on a no-code platform, read Add CAIRL to a base44 app after this page for copy-paste code.

Two terms you will see everywhere

• HVF (hosted verification flow) — the CAIRL-hosted pages your users go through to sign in, verify their identity, and approve sharing a result with your site. You redirect to it; you do not build it.
• VAE (Verified Access Event) — the billable event recorded when your server successfully exchanges an authorization code for a token for a returning verified user. Live credentials are charged per VAE; test credentials are not charged.

The glossary has the full list.

Step 0 — Set up your account (about 5 minutes)

The whole path is: create an account, add your website, copy the test credentials shown on Integration setup, accept the suggested callback URL (or type your own), wire your site (Steps 1–5), load funds, then create live credentials with one click. The first four are below.

1. Create a CAIRL account. Sign up at cairl.app/register and confirm your email.
2. Add your website as a business facet. Open /home/facets/new?type=business. Fill in the name, your website URL, and a short use case. Under Business mode choose My website or app, and choose an Organization type; the form requires both. Click Create business facet. Both settings can be changed later at /home/f/{slug}/config.
3. Copy your test credentials. Creating the facet also creates a pair of test credentials. Open the Integration setup page at /home/f/{slug}/integrate (replace {slug} with the slug shown after you created the facet, for example b-yoursite). The Your test credentials card shows the client ID and client secret once, with a copy button for each. Save both somewhere safe, then click I've saved these. CAIRL stores only a fingerprint of the secret, so it cannot be shown again; if you lose it, generate a new pair on /home/f/{slug}/keys (the pair created with the facet is listed there as Default test credentials). Test credentials need no funds and accept http://localhost callbacks. They run the real sign-in and consent flow — test with your own CAIRL account — and only the claim values, the sub, and billing are synthetic. You do not need to complete identity verification to test. See what is real and what is synthetic in test mode.
4. Register your callback URL. On /home/f/{slug}/connect (CAIRL:connect), stay on the Sandbox tab. Because the facet has a website, CAIRL suggests https://<your-site>/auth/cairl/callback; click Use this to register it, or type your own (for example http://localhost:3000/callback while developing) and click Add. Nothing is registered until you click. The URL must match the redirect_uri you send later character for character; query strings, fragments, and wildcards are not accepted.

The Integration setup page is also a checklist: it links to every remaining step and shows what is still missing.

If a Sandbox page is available in your environment at /home/developer/sandbox, it runs a keyless synthetic demo of the flow. It is optional and is not required for any step on this page.

1. What you will call

There is no refresh token. An ID token is issued only on the OIDC sign-in path (openid alone, on a login-enabled credential), never on a verification-scope exchange — see Log in with CAIRL.

"Freshness" here means the time-based policies only, and only on a live key. With a live key, /oauth/authorize enforces daily, 3day, weekly, biweekly and monthly: a member whose last verification falls outside that window is sent back through verification. The two event-driven policies, session and transaction, are not checked at that door today — a key on either one is treated as fresh there, so do not read the redirect as proof of a per-session or per-transaction check.

With a test key none of this applies. /oauth/authorize skips the depth and freshness gates entirely and the exchange returns fixture claims, so a stale or wholly unverified member sails through. A sandbox run therefore cannot tell you whether your stale-user handling works — only a live key exercises it.

2. Your credentials

# Shown once on /home/f/{slug}/integrate — test credentials look like this:
CAIRL_CLIENT_ID=cairl_test_your_client_id
CAIRL_CLIENT_SECRET=your_client_secret

Keep the secret on your server only. It is used at the token exchange step and must not appear in a web page or mobile app.

3. Send the user to CAIRL

Redirect users to CAIRL with the scopes your business requires. The example uses the hosted verification entry, which verifies the person afresh for your site; for a sign-in button that should recognise members CAIRL has already verified, use /oauth/authorize with response_type=code and the same parameters (see the quickstart's Step 1).

GET https://cairl.app/verify/start
  ?client_id=cairl_test_your_client_id
  &redirect_uri=https://yoursite.com/auth/cairl/callback
  &state=random_csrf_token_16_chars_min
  &scope=age:18+ identity:verified
  &code_challenge=pkce_s256_challenge
  &code_challenge_method=S256

Scopes vs. claim names. What you put in scope is the wire scope (age:18+, identity:verified). What comes back in the userinfo response is the claim name (claims.age_18_plus, claims.identity_verified). Sending a claim name as a scope (for example scope=age_18_plus) is rejected with invalid_scope. The full list is in the claims reference.

4. Handle the callback

After the user completes verification and approves sharing, CAIRL redirects back to your callback URL with code and state. Check that state matches the value you generated, then exchange the code from your server:

POST https://cairl.app/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=cairl_test_your_client_id
&client_secret=your_client_secret
&code=authorization_code
&redirect_uri=https://yoursite.com/auth/cairl/callback
&code_verifier=pkce_code_verifier

All six fields are required. PKCE (code_challenge in step 3, code_verifier here) is mandatory. authorization_code is the only grant type.

5. Read verified claims

The token response includes an access token. Use it to read the claims snapshot from userinfo.

GET https://cairl.app/api/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

{
  "sub": "pws_v1_abc123",
  "mode": "live",
  "evaluated_at": "2026-05-03T10:00:00.000Z",
  "claims": {
    "age_18_plus": true,
    "identity_verified": true
  },
  "meta": {
    "claims_requested": ["age_18_plus", "identity_verified"],
    "claims_resolved": ["age_18_plus", "identity_verified"],
    "claims_null": [],
    "claims_ignored": []
  }
}

Your systems receive the claim. The personal data that produced it stays on CAIRL's side of the boundary. sub is a stable identifier for this user on your site; use it to recognise them next time. mode tells you whether the response came from a test or a live key; with test credentials the claims are fixtures and the sub is a random pws_v1_test_… value.

Going live

1. Add funds at /home/f/{slug}/billing (Add Funds, $50 minimum load).
2. On /home/f/{slug}/connect, switch to the Live tab and add your production callback URL. CAIRL suggests the same https://<your-site>/auth/cairl/callback here; click Use this, or add your own. Live callbacks must use https://.
3. On /home/f/{slug}/keys, click Create live credentials. The button appears once funds are loaded, and nothing is created until you click it. The live client ID and secret are shown once, in the same dialog as your test credentials; copy both before closing it. The + Generate Key dialog is still there if you want a live key with your own label or a chosen set of Required Claims.
4. Swap the client ID and secret in your server configuration.

With live credentials the token exchange returns 402 payment_required when the balance is insufficient, and no token is issued.

Next steps

• Quickstart with full working code
• Add CAIRL to a base44 app (no developer required)
• Claims reference
• Display the CAIRL trust badge
• Glossary