Claims Reference

Overview

CAIRL returns verified claims — boolean or structured assertions about a user's identity — instead of raw identity data. You never receive documents, names, or PII. You receive only the specific claims you requested.

Claims are returned in two places:

• The access token JWT (decoded client-side or server-side)
• The /api/oauth/userinfo endpoint response
• The claims field of vae.resolved webhook events

Requesting claims

Specify claims using the scope parameter in the authorization URL. Multiple claims are space-delimited:

scope=age_18_plus identity_verified document_active

Users see exactly what you request on CAIRL's consent screen. Request only what your application needs.

Claim reference

Identity claims

Freshness claims

Freshness policy is configured per API key (daily, weekly, monthly, quarterly, annual). If the user's last full verification is older than your policy window, freshness_current is false.

Comparison claims

These claims require the user to submit data (name, date of birth, address) which CAIRL compares against the verified identity record. The comparison result — match or no-match — is returned, not the data itself.

Comparison claims require the partner to be at the activation funnel stage. Contact CAIRL to enable them.

Claim values

Claims are always returned with their requested values:

{
  "sub": "pws_v1_abc123...",
  "age_18_plus": true,
  "identity_verified": true,
  "document_active": true,
  "freshness_current": false
}

A claim is only false if the user fails the check — not because data is unavailable. If a claim cannot be evaluated (e.g., the user's document is too old to evaluate freshness), CAIRL returns the most conservative value.

The sub field

Every token and userinfo response includes sub — a stable, per-partner pseudonymous user identifier:

pws_v1_abc123def456...

Properties of sub:

• Stable — the same user always gets the same sub with your application
• Per-partner — the same user has a different sub with each CAIRL partner (prevents cross-partner tracking)
• Non-reversible — CAIRL cannot reverse-engineer the real user from sub

Use sub as the stable identifier to link returning users to your application's records.

Claims and billing

Billing occurs at the token exchange step — only when you successfully retrieve a token. Abandoned sessions and failed exchanges are not billed.

Evaluation timing

Claims are evaluated at token exchange, not at verification time. This means:

• If a user's document expires between their verification and your token exchange, document_active will reflect the current state
• freshness_current is evaluated against your key's freshness policy at exchange time
• Comparison claims are evaluated with the submitted data you provided at verification initiation

Userinfo returns the issuance-time snapshot

GET /api/oauth/userinfo returns the claim values as evaluated when your access token was issued — not a live re-evaluation against the user's current state.

Why

Your partner consented to a specific set of claim values at the moment of token exchange. If a user's underlying state changes after that moment (a verification expires, an attribute is corrected), CAIRL would silently disclose the new state on every subsequent userinfo call if it re-evaluated live. That would be a state change the user did not authorize you to observe at consent time.

The contract is point-in-time: the userinfo response represents the user's state at the moment the token was issued, and that contract holds for the lifetime of the token.

Practical consequences

• The evaluated_at field in the userinfo response is the token issuance timestamp, not the time of the userinfo call. For a given token, this value is stable across requests.
• A backend mutation (verification renewal, attribute change) between token issuance and your userinfo call does not change the values returned by userinfo for that token.
• To get fresh claims, request a new token via the standard authorization flow. The new token captures a new snapshot at its issuance time. This is also the consent-renewal point.

What does NOT change

• Token revocation continues to work as before — a revoked token returns 401 from userinfo regardless of what the snapshot contains. See the token revocation docs.
• Token expiry is enforced as before. Snapshot semantics apply only to the lifetime of an unrevoked, unexpired token.

Response shape

{
  "sub": "pws_v1_<pairwise>",
  "evaluated_at": "2026-05-03T10:00:00.000Z",
  "claims": {
    "age_18_plus": true,
    "email_verified": true
  },
  "meta": {
    "claims_requested": ["age_18_plus", "email_verified"],
    "claims_resolved": ["age_18_plus", "email_verified"],
    "claims_null": [],
    "claims_ignored": []
  }
}

meta.claims_ignored is reserved for future use; treat its absence as "the evaluator did not flag any claims as ignored at issuance."

Adding claims after launch

You can request additional claims by updating the scope parameter in your authorization URL. Users will see the new claims on the consent screen the next time they authenticate.

If you require comparison claims (name_match, dob_match, address_match), contact CAIRL to enable them for your account.