OAuth2 API

OAuth2 flow integration guide for AgeVerif's age verification process.

⚠ Read the Checker Script documentation first

It is recommended to read the Checker Script documentation before proceeding with this integration

Checker Start Selfie OAuth2 Checker Start

Requirements

Be registered on our Webmasters Platform as a webmaster, available at https://webmasters.ageverif.com.
Have a website registered on the platform: https://webmasters.ageverif.com/website/add.
Enable the AgeVerif OAuth2 feature on your website, obtaining a Client ID and Client Secret.
Be familiar with OAuth2 protocol to correctly implement it in their application.

The full OAuth 2.0 Authorization Framework RFC can be found here.

High-Level Example

A new visitor enters your website.
The visitor clicks on the "Verify with AgeVerif" button on your website.

You open a new window and redirect the visitor to AgeVerif's Authorization endpoint.

http

GET https://api.ageverif.com/v1/oauth2/checker
    ?response_type=code
    &client_id=<client_id>
    &redirect_uri=https://example.org/oauth2-callback
    &scope=read
    &state=<state>

The visitor accepts the authorization prompt and verifies their age on AgeVerif.

The visitor is redirected to the given redirect_uri with code and state parameters.

http

GET https://example.org/oauth2-callback
    ?code=<code>
    &state=<state>

You verify the state and exchange the code for an access_token by contacting AgeVerif's Token endpoint.

bash

curl -X POST https://api.ageverif.com/v1/oauth2/token \
    -H "Authorization: Basic <base64(client_id:client_secret)>" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=authorization_code" \
    -d "code=[code]" \
    -d "redirect_uri=https://example.org/oauth2-callback"

You use the access_token to request visitor resources from AgeVerif's Resources endpoint.
Obtaining "resources" is optional
If you get a valid response from the previous step, the visitor is guaranteed to be verified on the current region.
bash
```
curl -X GET https://api.ageverif.com/v1/oauth2/resources \
    -H "Authorization Bearer <access_token>"
```
You should now allow the visitor to access the content on your website.

Button Style Guidelines

You can choose between two flows:

Age Verification Flow - Opens AgeVerif's age verification process.
Login Flow - Opens AgeVerif's login page.

Interchangeable flows

These two flows can be used interchangebly. The visitor can still verify their age on the login flow or login on the age verification flow. The only difference is the landing page.

Logo, Colors and Shape

You can use the following colors for the button background:

AgeVerif Blue: #004db3
White: #ffffff
Black: #000000
Neutral shades of gray (non-color accents): E.g. #e0e0e0

You must use one of the AgeVerif logos provided below and ensure its visibility depending on the button's background color.

Download Button Icons

The button label/text must be clearly visible with a good contrast ratio against the button background color.

The shape of the button can be whatever you want, in line with your website's design.

Recommended button labels

The button label must be in the language of your website and should be clear and concise. Here are some allowed button labels to use on your website:

Language
en	Continue with AgeVerif	Login with AgeVerif	Sign in with AgeVerif
fr	Continuer avec AgeVerif	Connexion avec AgeVerif	S'identifier avec AgeVerif
pt	Continuar com AgeVerif	Iniciar sessão com AgeVerif	Fazer login com AgeVerif
es	Continuar con AgeVerif	Iniciar sesión con AgeVerif	Identificarse con AgeVerif
it	Continua con AgeVerif	Accedi con AgeVerif	Identificati con AgeVerif
de	Fortfahren mit AgeVerif	Anmelden mit AgeVerif	Identifizieren mit AgeVeri

Age Verification Flow

Language
en	Verify with AgeVerif	Verify age with AgeVerif	Prove age with AgeVerif
fr	Vérifier avec AgeVerif	Vérifier l'âge avec AgeVerif	Prouver l'âge avec AgeVerif
pt	Verificar com AgeVerif	Verificar idade com AgeVerif	Provar idade com AgeVerif
es	Verificar con AgeVerif	Verificar edad con AgeVerif	Probar edad con AgeVerif
it	Verifica con AgeVerif	Verifica età con AgeVerif	Prova età con AgeVerif
de	Überprüfen mit AgeVerif	Alter überprüfen mit AgeVerif	Alter nachweisen mit AgeVeri

Endpoints

The OAuth2 flow consists of three endpoints:

Authorization - The visitor is redirected to AgeVerif's authorization page to accept/deny the authorization request.
Token - You exchange the authorization code for an access_token to be used in the next step.
Resources - You can request visitor resources using the access_token obtained in the previous step.

1. Authorization

The OAuth2 process must be initiated with a click from the visitor on a "Verify with AgeVerif" button.

Your website must open a new window to the Authorization endpoint:

http

GET https://api.ageverif.com/v1/oauth2/checker

Optionally, you can use the login endpoint, initialized with a click from the visitor on a "Login with AgeVerif" button.

http

GET https://api.ageverif.com/v1/oauth2/login

Parameters

Field	Type	Format	Description
client_id	string	E.g. `V61LHMuuwahgYDcGnagso`	Your website's Oauth2 Live Client ID, found in the Webmasters Platform
redirect_uri ^[1]	string	E.g. `https://example.org/oauth2-callback`	Callback URI where visitor will be redirected after accepting/denying authorization. Recommended to URL-encode this parameter.
response_type	string	E.g. `code` Default: `code`	Response type. Only `code` is available at the moment
scope	string (optional)	E.g. `read` Default: `read`	Permission scope. Only `read` is available at the moment
state ^[2]	string (optional)	E.g. `abc123`	Optional string to verify state was kept between calls
language	string (optional)	E.g. `en` Available: `auto`,`de`,`en`,`es`,`fr`,`it`,`pt` Default: `auto`	Forces a given language. Auto is based on the visitor's browser language, with fallback to `en` if not available.
challenges	comma separated values (optional)	E.g. `selfie,ticket` Available: `agego`, `agekey`, `anonymage`, `credit_card`, `pleenk`, `selfie`, `ticket`, `yoti`	Loads only the given challenges. If only one is provided, the Checker* will land on that challenge*.

[1] Redirect URI parameter

It is recommended to URL-encode this parameter to avoid issues with special characters and collisions with other parameters.

E.g. https://example.org/oauth2-callback becomes https%3A%2F%2Fexample.org%2Foauth2-callback.

[2] State parameter

It is your responsibility to verify the state value was kept when the visitor is redirected to redirect_uri to prevent CSRF attacks.

Response

After accepting/denying authorization, the visitor is redirected to the given redirect_uri with the same state sent in the initial request and a code to be used in the Token endpoint.

⏱ The code is valid for 10 minutes

🟢 200 OK

https://example.org/oauth2-callback
?code=<code>
&state=<state>

Field	Type	Format	Description
code	string	E.g. `8f0FwyzmlDSfdOiE...`	Used on next step to exchange for an `access_token`
state	string (optional)	E.g. `abc123`	Optional string to verify state was kept between calls (provided by the Webmaster)

Example

Your website opens a new browser window to:

http

https://api.ageverif.com/v1/oauth2/checker
  ?client_id=V61LHMuuwahgYDcGnagso
  &redirect_uri=https%3A%2F%2Fexample.org%2Foauth2-callback
  &response_type=code
  &scope=read
  &state=abc123

The visitor accepts the prompt on AgeVerif website.

The visitor is redirected back to:

http

https://example.org/oauth2-callback
  ?code=8f0FwyzmlDSfdOiEaTjxJPXBeBEfCYrvkLyrHoM3DRZMvbaiBciebOgKfKjwWCwk
  &state=abc123

Your website verifies the state against the one sent in the initial request and proceeds to the next step.

2. Token

After the visitor's age verification and a successful redirection to your redirect_uri, your website must exchange the authorization grant code obtained in the previous step with an access_token.

http

POST https://api.ageverif.com/v1/oauth2/token

Headers

Field	Format	Description
Authorization	E.g. `Basic <base64(client_id:client_secret)>`	Basic authentication header with your OAuth2 Live Client ID and Client Secret, found in the Webmasters Platform

Information about Basic Access Authorization can be found here.

Parameters

Content-Type: application/x-www-form-urlencoded

Field	Type	Format	Description
grant_type	string	E.g. `authorization_code`	Provided authorization grant type. Available: `authorization_code`, `portable_verification` Only `authorization_code` should be used for this flow.
code	string	E.g. `8f0FwyzmlDSfdOiE...`	Authorization grant code returned from previous step
redirect_uri	string	E.g. `https://example.org/oauth2-callback`	Must be the same used in the previous authorization prompt

Client Authentication

You can authenticate either by Authorization header or by sending client_id and client_secret as parameters in the request body.

Check the Portable Verifications integration for more details on the portable_verification grant type.

Response

The response contains an access_token and a token_type that can be used in the next step.

Content-Type: application/json

🟢 200 OK

json

{
  "token_type": "Bearer",
  "access_token": <access_token>,
  "expires_at": <expires_at>,
  "expires_in": <expires_in>,
}

Field	Type	Format	Description
token_type	string	`Bearer`	Hint for how token should be used. Only `Bearer` is available
access_token	string	E.g. `eyJ0eXAiOiJKV1Qi...`	Used to fetch user data on Resources endpoint
expires_at	integer	E.g. `781045200`	Unix timestamp when the token expires
expires_in	integer	E.g. `3600`	Seconds until token expires

Example

You send an authenticated server-side request with the code obtained in the previous step to the Token endpoint:

bash

curl -X POST https://api.ageverif.com/v1/oauth2/token \
  -H "Authorization: Basic V61LHMuuwahgYDcGnPC5bbWobLw7BzR..." \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=8f0FwyzmlDSfdOiE..." \
  -d "redirect_uri=https://example.org/oauth2-callback"

Response:

json

{
  "token_type": "Bearer",
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "expires_at": 781045200,
  "expires_in": 3600,
}

You receive an access_token and can now use it to request visitor resources on the Resources endpoint.

3. Resources

After obtaining the access_token, you can use it to request visitor resources.

http

GET https://api.ageverif.com/v1/oauth2/resources

Obtaining "resources" is optional

If you get a valid response from the previous step, the visitor is guaranteed to be verified.

Headers

Field	Format	Description
Authorization	E.g. `Bearer eyJ0eXAiOiJKV1Qi...`	`access_token` returned from previous step

Parameters

Field	Type	Format	Description
resources	string[] (optional)	E.g. `verification`	Array with visitor resources to return. Available: `verification`, `portable_verification` Default: `verification`

Check the Portable Verifications integration for more details on the portable_verification resource.

Response

🟢 200 OK

json

{
  "resources": {
    "verified": true,
    "uid": <uid>,
    "country": <country>,
    "country_subdivision": <country_subdivision>,
    "assurance_level": <assurance_level>,
    "age_threshold": <age_threshold>,
    "reused": <reused>,
    "expires_at": <expires_at>,
    "expires_in": <expires_in>
  }
}

Resources:

Field	Type	Format	Description
verified	boolean	E.g. `true`	Whether the visitor is verified - always `true`
uid	string	E.g. `F1Hkgz2lvaUdF8Ia8WNBL`	Unique identifier for the verification
country	string(2)	E.g. `US`	Country (ISO 3166-1 alpha-2) of the visitor
country_subdivision	string\|null	E.g. `US-CA`	Country Subdivision (ISO 3166-2) of the visitor
assurance_level	string	E.g. `STRICT`	Assurance level according to IEEE Standard for Online Age Verification (IEEE 20891-2024). Available: `STANDARD`,`ENHANCED`,`STRICT`
age_threshold	integer	E.g. `18`	Age threshold of the verification
reused	boolean	E.g. `true`	Whether the verification was reused from a previous session (i.e. the visitor logged in or was already verified)
expires_at	integer	E.g. `781045200`	Unix timestamp when the verification expires
expires_in	integer	E.g. `3600`	Seconds until the verification expires

Example

You send an authenticated server-side request to the Resources endpoint with the access_token obtained in the previous step:

bash

curl -X GET https://api.ageverif.com/v1/oauth2/resources \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Qi..."

Response:

json

{
  "resources": {
    "verified": true,
    "uid": "F1Hkgz2lvaUdF8Ia8WNBL",
    "country": "US",
    "country_subdivision": "US-CA",
    "assurance_level": "STRICT",
    "age_threshold": 18,
    "reused": true,
    "expires_at": 781045200,
    "expires_in": 3600
  }
}

JavaScript API (ageverif)

Examples

WordPress/WooCommerce

Shopify

1. Authorization

2. Token

3. Resources

Checker Script Integration

API Integration

OAuth2 API

Requirements

High-Level Example

Button Style Guidelines

Logo, Colors and Shape

Recommended button labels

Age Verification Flow

Endpoints

1. Authorization

Parameters

Response

Example

2. Token

Headers

Parameters

Response

Example

3. Resources

Headers

Parameters

Response

Example

OAuth2 API ​

Requirements ​

High-Level Example ​

Button Style Guidelines ​

Logo, Colors and Shape ​

Recommended button labels ​

Login Flow ​

Age Verification Flow ​

Endpoints ​

1. Authorization ​

Parameters ​

Response ​

Example ​

2. Token ​

Headers ​

Parameters ​

Response ​

Example ​

3. Resources ​

Headers ​

Parameters ​

Response ​

Example ​

OAuth2 API

Requirements

High-Level Example

Button Style Guidelines

Logo, Colors and Shape

Recommended button labels

Login Flow

Age Verification Flow

Endpoints

1. Authorization

Parameters

Response

Example

2. Token

Headers

Parameters

Response

Example

3. Resources

Headers

Parameters

Response

Example