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

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

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.