OAuth 2.0 Flow

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

Step 1: Redirect to verification

Endpoint

Open the verification app and pass the query string on the site root. There is no /verify path.

GET https://app.ageonce.com/?client_id=...&redirect_uri=...&state=...&age_required=18

Parameters

Parameter	Type	Required	Description
`client_id`	string	Yes	Your Client ID
`redirect_uri`	string	Yes	URL for user redirect after verification
`state`	string	Recommended	Random string for CSRF protection
`age_required`	string	Optional	Minimum age to verify (e.g. `18`, `21`). Default: `18`

Example URL

https://app.ageonce.com/?client_id=ap_live_your_client_id&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&state=xyz789&age_required=18

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

A failed or cancelled check stays on the AgeOnce page. The browser is redirected to redirect_uri only after a successful check, with code and state.

Step 4: Exchange code for token

Your backend exchanges code for access_token:

POST https://api.ageonce.com/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 /?client_id=...                │
     │────────────────────────────────────────►│
     │                                         │
     │         2. User verifies age            │
     │                                         │
     │  3. Redirect: callback?code=...        │
     │◄────────────────────────────────────────│
     │                                         │
     │  4. POST api.ageonce.com/api/oauth/token   │
     │────────────────────────────────────────►│
     │                                         │
     │  5. { access_token: "..." }            │
     │◄────────────────────────────────────────│
     │                                         │

Lifetime

Element	Lifetime
Authorization code	1 minute
Access token (`access_token`)	10 minutes (`expires_in`: 600)

OAuth Flow