Versioning and Changelog

Versioning policy

The public integration docs describe the current CAIRL hosted verification beta. During beta, CAIRL treats the OAuth authorization flow, token exchange, userinfo claim response, and webhook event names as compatibility-sensitive surfaces.

Expected change types:

Change type	Compatibility expectation
New claim	Additive; existing scopes continue to work
New webhook event	Additive; consumers should ignore unknown event types
New optional field	Additive; consumers should ignore unknown fields
Required request field	Breaking; announced before rollout
Response field removal or rename	Breaking; announced before rollout

Webhook consumers should validate required fields and ignore unknown fields so additive releases do not break production integrations.

Current public surface

Area	Current docs
Hosted verification	Verification sessions
OAuth provider	OAuth and OIDC guide
Token exchange	Quickstart
Webhooks	Webhooks
Claims	Claims
Shopify apps	Shopify app integration

Changelog

2026-09-02

Corrected every scope example to the wire scopes the authorization endpoint accepts (age:18+, identity:verified, freshness:current, ...). Claim names such as age_18_plus are response keys, not scopes, and are rejected with invalid_scope when sent as scopes.
Restricted the claims reference to scopes that are requestable today and moved the rest under "Planned (not yet requestable)".
Added exact dashboard paths for keys, callback URLs, and funds, and a Step 0 account-setup walkthrough to Getting Started.
Added Add CAIRL to a base44 app and a glossary.
Documented that there is no OpenID discovery document, refresh token, or ID token, and that client_inactive is an authorization-stage error.

2026-06-03

Added a public OpenAPI JSON contract at /openapi.json and an API reference page covering hosted verification, OAuth, verification sessions, Shopify exchange, and webhook callback schemas.
Corrected the Getting Started and quickstart examples so userinfo claims are read from the claims object returned by /api/oauth/userinfo.
Added Python quickstart snippets for PKCE, token exchange, and userinfo claim retrieval.
Added a docs-backed homepage sample request for the OAuth token and userinfo endpoints.
Added Shopify app integration guidance.
Added the OAuth and OIDC guide.
Added public integration versioning and changelog guidance.
Added per-page "Edit on GitHub" links to the docs site.