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.

Upgrade endpoint

cURL

curl -X POST "https://api.agekey.org/v1/agekey/upgrade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64(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"}}]}'

JavaScript

const axios = require('axios');

const accessToken = 'your-access-token';
const credentials = Buffer.from(`${accessToken}:`).toString('base64');

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'
      }
    }]
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Basic ${credentials}`
    }
  }
);

Python

import requests
import base64
import json

access_token = 'your-access-token'
credentials = base64.b64encode(
    f'{access_token}:'.encode()
).decode()

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'
            }
        }]
    },
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Basic {credentials}'
    }
)

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Basic <base64(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	No	Verification source path (for example /veratad/roc, /in_house/fae)

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

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

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 with an empty response body:

{}

note

Success is indicated by the 200 status code. The response body is empty.