Getting Started

This guide walks your business through the fastest path to a working CAIRL integration: run a product in Sandbox, then graduate to test credentials, then request live credentials only after production gates are complete.

Prerequisites

• A CAIRL business account
• For the first Sandbox run: no API key, client secret, redirect URI, or wallet balance
• For test integration: test credentials and a redirect URI
• For live integration: production approval, live credentials, and wallet readiness

1. Start in Sandbox

Sign in and open Sandbox. Choose Checkbox, OAuth, or Connect, then run the recipe against CAIRL's synthetic fixtures.

Sandbox recipes are intentionally keyless. They show the partner-side configuration, customer-facing experience, and response shape without creating a real verification session, billable VAE, wallet debit, enrollment, or production claim.

2. Generate test credentials

When you are ready to call the API from your own application, create test credentials from the dashboard. Test credentials use the live API contract but return deterministic, non-production responses.

# Your credentials will look like this:
CAIRL_CLIENT_ID=cairl_test_your_client_id
CAIRL_CLIENT_SECRET=your_client_secret

3. Initiate the verification flow

Redirect users to CAIRL's hosted verification flow with the claim scopes your business requires.

GET https://cairl.app/verify/start
  ?client_id=cairl_test_your_client_id
  &redirect_uri=https://yourapp.com/callback
  &state=random_csrf_token
  &scope=age_18_plus identity_verified
  &code_challenge=pkce_s256_challenge
  &code_challenge_method=S256

4. Handle the callback

After the user completes verification and authorizes sharing, CAIRL redirects back to your application with an authorization code.

POST https://cairl.app/api/oauth/token
  client_id=cairl_test_your_client_id
  &client_secret=your_client_secret
  &code=authorization_code
  &grant_type=authorization_code
  &redirect_uri=https://yourapp.com/callback
  &code_verifier=pkce_code_verifier

5. Receive verified claims

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

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

{
  "sub": "pws_v1_abc123",
  "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. Swap to live credentials only after CAIRL approves production access and your wallet is ready for billable events.

Next steps

• Display the CAIRL trust badge on your platform
• Read the API reference
• Review brand usage requirements for referencing CAIRL
• Read the asset policy for distribution rules