OAuth 2.0 Flow

AgeOnce uses the standard OAuth 2.0 Authorization Code Flow for age verification.

Step 1: Redirect to verification

Endpoint

GET https://app.ageonce.com/verify

Parameters

Parameter	Type	Required	Description
`client_id`	string	Yes	Your Client ID
`redirect_uri`	string	Yes	URL for user redirect
`state`	string	Recommended	Random string for CSRF protection

Example URL

https://app.ageonce.com/verify?client_id=cl_abc123&redirect_uri=https://example.com/callback&state=xyz789

Important

redirect_uri must be pre-registered in your AgeOnce Dashboard.

Step 2: User completes verification

On the AgeOnce page:

User grants camera permission
Completes biometric verification
System determines age compliance

Step 3: Redirect back with code

After successful verification, the user is redirected to your redirect_uri:

https://example.com/callback?code=auth_code_123&state=xyz789

Callback parameters

Parameter	Description
`code`	Authorization code to exchange for token
`state`	Same state you sent

Errors

On error, redirect contains:

https://example.com/callback?error=access_denied&error_description=User%20cancelled

Error	Description
`access_denied`	User declined verification
`verification_failed`	Verification failed
`invalid_request`	Invalid request parameters

Step 4: Exchange code for token

Your backend exchanges code for age_token:

POST /api/oauth/token

Learn more about Token Exchange →

State parameter

State is used for CSRF attack protection:

// Generate state
const state = crypto.randomBytes(16).toString('hex');

// Store in session
session.oauthState = state;

// On callback - verify
if (req.query.state !== session.oauthState) {
  throw new Error('Invalid state');
}

Always verify state! Without this, your app is vulnerable to CSRF attacks.

Flow diagram

┌──────────┐                              ┌──────────┐
│  Client  │                              │ AgeOnce  │
└────┬─────┘                              └────┬─────┘
     │                                         │
     │  1. GET /verify?client_id=...          │
     │────────────────────────────────────────►│
     │                                         │
     │         2. User verifies age            │
     │                                         │
     │  3. Redirect: callback?code=...        │
     │◄────────────────────────────────────────│
     │                                         │
     │  4. POST /api/oauth/token              │
     │────────────────────────────────────────►│
     │                                         │
     │  5. { age_token: "..." }               │
     │◄────────────────────────────────────────│
     │                                         │

Lifetime

Element	Lifetime
Authorization code	1 minute
Age token	10 minutes

OAuth Flow