Upgrade AgeKey

The Upgrade AgeKey endpoint updates an existing AgeKey with a new verification result. The AgeKey to upgrade is identified by the access token obtained from exchanging the authorization code returned when using the agekey.upgrade scope.

Browser step before this API call

The upgrade flow starts by redirecting the user to /v1/oidc/use with the agekey.upgrade scope. That redirect URL supports the same optional language query parameter as the standard Use flow; see Use AgeKey Authorization.

Upgrade endpoint

cURL

curl -X POST "https://api.agekey.org/v1/agekey/upgrade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{"authorization_details":[{"type":"age_verification","age":{"date_of_birth":"2000-01-02"},"method":"id_doc_scan","verification_id":"b861f598-f58a-49e9-b98a-a2ee5bdfb4bb","verified_at":"2025-10-07T12:34:56Z","attributes":{"face_match_performed":true,"issuing_country":"US"},"provenance":"/veratad/roc"}]}'

JavaScript

const axios = require('axios');

const accessToken = 'your-access-token';

const response = await axios.post(
  'https://api.agekey.org/v1/agekey/upgrade',
  {
    authorization_details: [{
      type: 'age_verification',
      age: { date_of_birth: '2000-01-02' },
      method: 'id_doc_scan',
      verification_id: 'b861f598-f58a-49e9-b98a-a2ee5bdfb4bb',
      verified_at: '2025-10-07T12:34:56Z',
      attributes: {
        face_match_performed: true,
        issuing_country: 'US'
      },
      provenance: '/veratad/roc'
    }]
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

Python

import requests
import base64
import json

access_token = 'your-access-token'

response = requests.post(
    'https://api.agekey.org/v1/agekey/upgrade',
    json={
        'authorization_details': [{
            'type': 'age_verification',
            'age': {'date_of_birth': '2000-01-02'},
            'method': 'id_doc_scan',
            'verification_id': 'b861f598-f58a-49e9-b98a-a2ee5bdfb4bb',
            'verified_at': '2025-10-07T12:34:56Z',
            'attributes': {
                'face_match_performed': True,
                'issuing_country': 'US'
            },
            'provenance': '/veratad/roc'
        }]
    },
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}'
    }
)

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer <access_token>	Yes

Body

Property	Type	Required	Description
authorization_details	array	Yes	JSON array of verification data

Authorization details format

The authorization_details parameter must be a JSON array containing age verification information:

Field	Type	Required	Description
type	string	Yes	Always age_verification
age	object	Yes	Age information object
age.date_of_birth	string	No*	Date of birth in ISO 8601 format (YYYY-MM-DD)
age.at_least_years	number	No*	Minimum age threshold verified
age.years	number	No*	Exact age in years
method	string	Yes	Verification method used (see supported methods below)
verification_id	string	Yes	A unique ID for revoking or auditing the verification. The ID is chosen by you, the contributor, not by the AgeKey service. Up to 100 characters. Alphanumeric plus _+/=.-. UUID v7 format is recommended.
verified_at	string	Yes	Verification completion time (date or date-time in ISO 8601)
attributes	object	No	Method-specific verification attributes
provenance	string	Yes	Verification source path identifying where the age signal was obtained (for example /veratad/roc). Must be a value from the allowlist.

*Either date_of_birth, at_least_years, or years is required depending on the verification method.

Valid provenances

Provenance values are validated against an allowlist. You must pre-register the provenance values you use with your AgeKey representative. Contact AgeKey for the current list of valid provenances or to request adding a new provenance for your verification source.

Example:

[
  {
    "type": "age_verification",
    "age": {
      "date_of_birth": "2000-01-02"
    },
    "method": "id_doc_scan",
    "verification_id": "b861f598-f58a-49e9-b98a-a2ee5bdfb4bb",
    "verified_at": "2025-10-07T12:34:56Z",
    "attributes": {
      "face_match_performed": true,
      "issuing_country": "US"
    },
    "provenance": "/veratad/roc"
  }
]

Supported verification methods

Method	Age Format	Required Attributes*	Optional Attributes*
email_age_estimation	at_least_years	None	None
facial_age_estimation	at_least_years	None	on_device (boolean)
national_id_number	date_of_birth preferred	issuing_country (ISO 3166-1 alpha-2)	None
digital_credential	date_of_birth preferred	platform (singpass, connect_id, privy, digilocker, korean_real_name), issuing_country (ISO 3166-1 alpha-2)	None
id_doc_scan	date_of_birth preferred	None	face_match_performed (boolean), issuing_country (ISO 3166-1 alpha-2)
payment_card_network	at_least_years: 18	card_type (credit, debit, unknown)	None

*Attributes parsing is strict, if the attributes given for a particular method aren't required or optional then the request fails.

Response

On success, returns a status code of 200:

"OK"

note

Success is indicated by the 200 status code.