Developer Docs

Integrate CAGE like any modern identity provider.

CAGE implements OAuth 2.0 with OpenID Connect-style age claims. Redirect, exchange the code, verify the signed token, and enforce your age gate.

Request Credentials

Quick Start

Four calls from redirect to verified age.

You will receive a client ID, client secret, and registered redirect URI during partner onboarding.

01

Register

02

Redirect

03

Exchange

04

Verify

1. Redirect to CAGE

Send users to the authorization endpoint when they need to confirm age.

GET /oauth/authorize
https://api.cageid.app/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yoursite.com/callback
  &response_type=code
  &state=RANDOM_STATE
  &scope=openid%20age_verification
client_idYour partner client ID from CAGE onboarding.
redirect_uriMust match one of your registered callback URLs exactly.
stateRandom value you verify on callback to prevent CSRF.
scopeUse openid age_verification for age claims.

2. Exchange the code

Exchange the short-lived auth code server-side. Never expose your client_secret in browser code.

POST /oauth/token
grant_type=authorization_code
&code=AUTH_CODE_FROM_CALLBACK
&redirect_uri=https://yoursite.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

3. Read the age claims

id_token decoded
{
  "iss": "https://api.cageid.app",
  "sub": "anonymous_partner_scoped_id",
  "aud": "YOUR_CLIENT_ID",
  "age_verified": true,
  "age_floor": 18,
  "iat": 1741910400,
  "exp": 1741996800
}
subAnonymous user ID unique to your partner application.
age_verifiedTrue when CAGE issued the token after verification.
age_floor18 or 21, based on your registered policy.

4. Verify the signature

Fetch CAGE signing keys from the JWKS endpoint, verify the ID token signature, then validate iss, aud, and exp.

JWKS endpoint
GET https://api.cageid.app/.well-known/jwks.json

Errors

Handle declines and expired codes explicitly.

Auth codes expire quickly and are single-use. If verification is declined or a user cancels, send them through your normal age-gate fallback instead of treating the user as verified.