OAuth and OIDC Guide

Map CAIRL hosted verification into OAuth authorization and OIDC-style claim retrieval.

Overview

CAIRL's hosted verification flow uses OAuth 2.0 Authorization Code with PKCE. Your application redirects the user to CAIRL, receives an authorization code, exchanges the code server-to-server, and reads verified claims from the userinfo endpoint.

Use this guide when your application already has an OAuth or OIDC integration layer and you want to plug CAIRL into that layer without collecting identity documents yourself.

Authorization endpoint

Redirect users to:

https://cairl.app/verify/start

Required parameters:

Parameter	Description
`client_id`	Your CAIRL client identifier
`redirect_uri`	Exact callback URL registered with CAIRL
`state`	Random CSRF token, returned unchanged
`scope`	Space-delimited verified claims such as `age_18_plus identity_verified`
`code_challenge`	PKCE S256 challenge
`code_challenge_method`	Must be `S256`

See the Quickstart for complete Node and Python PKCE examples.

Token endpoint

Exchange the authorization code at:

POST https://cairl.app/api/oauth/token

The token request uses application/x-www-form-urlencoded and includes:

Field	Description
`grant_type`	`authorization_code`
`code`	Code from the callback
`client_id`	Your CAIRL client identifier
`client_secret`	Server-side secret from CAIRL
`redirect_uri`	Same callback URL used in the authorization request
`code_verifier`	Original PKCE verifier

The response includes a bearer access_token, token_type, and expires_in.

Userinfo and claim retrieval

Read verified claims at:

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

The response is OIDC-style: it includes a stable, per-partner sub plus the verified claims the user authorized. CAIRL does not return raw document images or default raw identity fields through this endpoint.

{
  "sub": "user_abc123",
  "age_18_plus": true,
  "identity_verified": true
}

OIDC compatibility notes

Treat sub as a pseudonymous subject identifier scoped to your CAIRL client.
Use scopes to request only the claims your product needs.
Validate state before exchanging the authorization code.
Store and use the client_secret only on your server.
Do not require an ID token for the public beta integration; use userinfo as the canonical claims response.

If your production launch requires OIDC discovery metadata, JWKS publication, or ID-token validation, contact your CAIRL onboarding contact before launch so the requirement can be reviewed against the current API contract.