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
JavaScript
Python

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"

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;

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
`can_create`	string	No	When present and `true`, users see both "Use AgeKey" and "Create AgeKey". When omitted or not `true`, only "Use AgeKey" is shown.
`language`	string	No	Optional IETF BCP 47 language tag (for example `en-US`, `pt-BR`) to set the AgeKey UI language for this redirect. When omitted, the UI follows the visitor's browser language preferences. Applies to use and upgrade flows, which both use this authorization URL.

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
`/yoti`	Yoti verification
`/meta`	Meta verification
`/friendly_id/amazon`	Friendly ID via Amazon
`/paymentico`	Paymentico verification

Overrides structure:

Each method key inside overrides accepts the following fields:

Field	Type	Required	Description
`min_age`	integer	No*	A single minimum age threshold for this method (0–150). For `facial_age_estimation`, exactly one of `min_age` or `age_thresholds` is required.
`age_thresholds`	array	No*	Per-threshold overrides that map 1:1 by index to the root `age_thresholds`. Each entry is the minimum age (for this method) required to satisfy the corresponding root threshold. Length must equal root `age_thresholds` length.
`verified_after`	string	No	Override `verified_after` for this specific method
`attributes`	object	No	Method-specific attribute requirements

*For facial_age_estimation, one of min_age or age_thresholds must be provided.

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"]
      }
    }
  }
}

Example with age_thresholds override for facial age estimation:

{
  "age_thresholds": [13, 18],
  "overrides": {
    "facial_age_estimation": {
      "age_thresholds": [16, 21]
    }
  }
}

In this example, root threshold 13 requires the facial age estimation to report at least 16, and root threshold 18 requires at least 21.

Example with min_age override for facial age estimation:

{
  "age_thresholds": [18],
  "overrides": {
    "facial_age_estimation": {
      "min_age": 21
    }
  }
}

Response

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

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

User chose to create an AgeKey

When you sent can_create=true and the user was shown the use-or-create dialog and chose to create an AgeKey, they're redirected with create_requested=true and no id_token. Your app should send them to complete verification with another method (such as ID document scan). Once that verification succeeds, direct them to the Create AgeKey flow.

https://yourapp.com/agekey/callback?
  state=abc123xyz789&
  create_requested=true

Query parameter	When present	Description
`id_token`	Success	Signed JWT with age threshold results. Must be validated on your server before trusting the results.
`state`	Always	The `state` value you sent; verify it for CSRF protection.
`code`	With `agekey_upgrade` scope	Returned when using the `agekey_upgrade` scope; can be exchanged to upgrade an AgeKey with a new verification.
`create_requested`	When `can_create=true` was sent	Present and `true` when the user chose "Create AgeKey" in the use-or-create dialog. Send the user to complete verification with another method; after success, direct them to the Create AgeKey flow. No `id_token` is returned. Only returned if the request included `can_create=true`.
`error`	On error	Error code (for example, `access_denied` when the user clicks back or abandons the flow); handle appropriately.

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.

ID token claims

The decoded id_token JWT payload contains the following claims:

Claim	Type	Description
`sub`	string	Session ID. A unique identifier for this verification session. You should log this value for invalidation auditing (see note below).
`iss`	string	Token issuer. Always `https://api.agekey.org/v1/oidc/use`.
`aud`	array	Audience. Contains your `client_id`.
`iat`	number	Issued-at timestamp (UNIX epoch seconds).
`exp`	number	Expiration timestamp (UNIX epoch seconds). Token is valid for 10 minutes.
`nonce`	string	The `nonce` value from your authorization request. Must match to prevent replay attacks.
`age_thresholds`	object	Map of requested threshold to boolean result. For example `{ "13": true, "18": false }`.
`req_claims_hash`	string	Base64url-encoded SHA-256 hash of the `claims` JSON you sent, for request integrity verification.
`c_hash`	string	(Only with `agekey.upgrade` scope) Code hash per OIDC spec §3.3.2.11.

Log the session ID

The sub claim is the session ID for this verification. Persist this value in your system alongside the verification outcome. If an age signal is later revoked or found to be fraudulent, this session ID is used for invalidation auditing to identify which verifications were affected. Without it, impacted sessions can't be traced back to your users.

Authorization endpoint​

Parameters​

Claims parameter​

Response​

ID token claims​

Authorization endpoint

Parameters

Claims parameter

Response

ID token claims