Use AgeKey Authorization

The Use AgeKey authorization endpoint initiates the age verification flow for users who already have an AgeKey. Your application should redirect the user's browser to this endpoint with the appropriate parameters to start the verification process.

OIDC Specification

This endpoint implements the OpenID Connect Implicit Flow with id_token response type.

Authorization endpoint

cURL

curl -X GET "https://api.agekey.org/v1/oidc/use" \
  -G \
  -d "scope=openid" \
  -d "response_type=id_token" \
  -d "client_id=your-client-id" \
  -d "redirect_uri=https://yourapp.com/agekey/callback" \
  -d "state=abc123xyz789" \
  -d "nonce=nonce456def" \
  -d "claims=%7B%22age_thresholds%22%3A%5B13%2C18%5D%7D"

JavaScript

const params = new URLSearchParams({
  scope: 'openid',
  response_type: 'id_token',
  client_id: 'your-client-id',
  redirect_uri: 'https://yourapp.com/agekey/callback',
  state: 'abc123xyz789',
  nonce: 'nonce456def',
  claims: JSON.stringify({ age_thresholds: [13, 18] })
});

const authUrl = `https://api.agekey.org/v1/oidc/use?${params.toString()}`;
window.location.href = authUrl;

Python

from urllib.parse import urlencode
import json

params = {
    'scope': 'openid',
    'response_type': 'id_token',
    'client_id': 'your-client-id',
    'redirect_uri': 'https://yourapp.com/agekey/callback',
    'state': 'abc123xyz789',
    'nonce': 'nonce456def',
    'claims': json.dumps({'age_thresholds': [13, 18]})
}

auth_url = f"https://api.agekey.org/v1/oidc/use?{urlencode(params)}"

Parameters

Parameter	Type	Required	Description
scope	string	Yes	Always set to openid, optionally can also set agekey_upgrade if upgrades are allowed
response_type	string	Yes	Always set to id_token
client_id	string	Yes	Your AgeKey client ID
redirect_uri	string	Yes	Where users return after verification
state	string	Yes	Client-generated value for CSRF protection and maintaining application state
nonce	string	Yes	Random value for replay protection
claims	string	Yes	URL-encoded JSON specifying age thresholds and other constraints

Claims parameter

The claims parameter must be a URL-encoded JSON object specifying which age thresholds to verify and filtering criteria:

Field	Type	Required	Description
age_thresholds	array	Yes	Array of age thresholds to verify (for example [13, 18, 21])
allowed_methods	array	No	Array of verification methods to accept. (for example ["id_doc_scan", "payment_card_network"]) All verification methods are considered when not provided.
verified_after	string	No	ISO 8601 date/datetime - only accept verifications after this date
overrides	object	No	Method-specific filtering rules (see overrides structure below)

Overrides structure:

Field	Type	Required	Description
min_age	integer	No*	Minimum age for facial_age_estimation (required if facial_age_estimation in allowed_methods)
verified_after	string	No	Override verified_after for this specific method
attributes	object	No	Method-specific attribute requirements

Example:

{
  "age_thresholds": [13, 18],
  "allowed_methods": ["id_doc_scan", "payment_card_network"],
  "verified_after": "2024-01-01",
  "overrides": {
    "id_doc_scan": {
      "attributes": {
        "issuing_country": ["US", "GB"],
        "face_match_performed": [true]
      }
    },
    "payment_card_network": {
      "attributes": {
        "card_type": ["credit_card"]
      }
    }
  }
}

Response

On success, users are redirected to your redirect_uri with an id_token, state, and potentially a code in the URL fragment:

https://yourapp.com/agekey/callback#
  id_token=eyJhbGc...long-jwt-string...&
  state=abc123xyz789

note

The id_token contains age threshold results and must be validated on your server before trusting the results.

The code is returned when using the agekey_upgrade scope and can be used to upgrade an AgeKey with a new verification.