API Reference
Public endpoint and webhook contract for CAIRL hosted verification integrations.
API Reference
This page is the human-readable companion to the machine-readable OpenAPI contract.
Use the reference when you need exact endpoint names, request bodies, response shapes, webhook event schemas, or auth requirements. Use the quickstart when you want a copy-paste path to a working OAuth + PKCE integration.
Machine-readable contract
- OpenAPI JSON:
/openapi.json - Production server:
https://cairl.app - Staging server:
https://staging.cairl.app
The contract covers the public integration surfaces CAI-188 requires:
| Area | Endpoint or surface | Purpose |
|---|---|---|
| Hosted verification | GET /verify/start | Redirect the user into CAIRL verification with PKCE. |
| OAuth provider | POST /api/oauth/token | Exchange an authorization code for a bearer access token. |
| OAuth provider | GET /api/oauth/userinfo | Read the issuance-time verified claims snapshot. |
| OAuth provider | POST /api/oauth/revoke | Revoke an access token under RFC 7009 semantics. |
| Verification sessions | GET /api/verify/hvf-session/{session_id} | Poll hosted verification session status. |
| Shopify integration | POST /api/integrations/shopify/verify/exchange | Exchange a Shopify-hosted verification code for claims. |
| Webhooks | Partner-configured HTTPS callback | Receive signed outbound lifecycle and billing events. |
Authentication summary
| Surface | Auth model |
|---|---|
/verify/start | Public redirect with registered client_id, redirect_uri, state, and PKCE challenge. |
/api/oauth/token | Server-to-server client_id plus client_secret. |
/api/oauth/userinfo | Authorization: Bearer ACCESS_TOKEN. |
/api/oauth/revoke | Server-to-server client_id plus client_secret. |
/api/verify/hvf-session/{session_id} | Authorization: Bearer YOUR_API_KEY. |
| Shopify exchange | HMAC headers: X-CAIRL-Integration-Id, X-CAIRL-Timestamp, and X-CAIRL-Signature. |
| Partner webhooks | X-CAIRL-Signature: sha256=<hex> over the raw body. |
Userinfo response shape
GET /api/oauth/userinfo returns a snapshot of the claims evaluated when the
token was issued. It does not re-evaluate claims live on every request.
{
"sub": "pws_v1_<pairwise>",
"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": []
}
}Read the claim value from response.claims.age_18_plus, not from a top-level
age_18_plus field.
Webhook event schemas
The OpenAPI webhooks.cairlEvents section defines the signed callback payloads
CAIRL can send to a partner endpoint:
verification.session.completedverification.session.failedenrollment.createdvae.resolved
All events include an event_id for idempotency. Partners should store seen
event IDs and acknowledge quickly with a 2xx response before doing slow work.
Compatibility rules
- Unknown response fields are additive and should be ignored by clients.
- Unknown webhook event types should be ignored and logged.
- New required request fields are compatibility-sensitive and will be recorded in the versioning changelog.
- CAIRL returns verified claims. It does not return raw identity documents or default raw PII through the public OAuth userinfo endpoint.