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
provenance	object	No	Filter by verification provider origin (see provenance structure below)
overrides	object	No	Method-specific filtering rules (see overrides structure below)

Provenance structure:

Provenance filtering allows you to control which verification providers are accepted based on their origin path. Each provider has a unique provenance path that identifies the verification technology used.

Field	Type	Description
allowed	array	Allowed provenance patterns. Use * suffix for prefix matching (for example /veratad/* matches all Veratad providers)
denied	array	Denied provenance patterns. Takes precedence over allowed. Use to exclude specific providers

Pattern matching:

• Patterns must start with / and use lowercase letters, numbers, and underscores
• Use /* suffix for prefix matching (for example /veratad/* matches /veratad/internal, /veratad/trinsic, and other paths under that prefix)
• Exact paths match only that specific provider (for example /stripe only matches Stripe)
• Maximum 10 patterns per array, each up to 100 characters

Example with provenance filtering:

{
  "age_thresholds": [18],
  "provenance": {
    "allowed": ["/veratad/*", "/stripe", "/singpass"],
    "denied": ["/veratad/internal"]
  }
}

In this example:

• All Veratad providers are allowed via the /veratad/* wildcard
• Stripe and Singpass verifications are explicitly allowed
• Veratad internal verifications are excluded (denied takes precedence over allowed)

Available provenances:

Provenance	Description
/connect_id	Connect ID verification
/stripe	Stripe identity verification
/inicis	Inicis verification (Korea)
/singpass	Singpass verification (Singapore)
/privy	Privy verification
/spruce_id	Spruce ID verification
/verify_my	VerifyMy verification
/privately	Privately verification
/veratad/internal	Veratad internal verification
/veratad/trinsic	Veratad via Trinsic
/veratad/cra	Veratad via CRA verification
/veratad/roc	Veratad via ROC verification

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 with method and attribute filtering:

{
  "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.