OAuth2 API

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

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.

Flow 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://www.ageverif.com/oauth2/checker
    ?response_type=code
    &client_id=[client_id]
    &redirect_uri=https://www.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://www.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://www.ageverif.com/api/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://www.example.org/oauth2-callback" \

(Optional) 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.
The only visitor resource available is verified.
This endpoint exists to comply with the OAuth2 specification and to allow for future resources.
bash
```
curl -X GET https://www.ageverif.com/api/oauth2/resources \
    -H "Authorization Bearer [access_token]"
```
You should now allow the visitor to access the content on your website.

⏳ Access Token Duration

The access_token is valid for 1 hour

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 (optional) - You can request visitor resources using the access_token obtained in the previous step.

1. Authorization

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

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

http

GET https://www.ageverif.com/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://www.ageverif.com/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	string	E.g. `https://www.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	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 string (optional)	E.g. `selfie,email_age,ticket` Available: `selfie`, `email_age`, `credit_card`, `ticket`, `anonymage`, `pleenk`	Loads only the given challenges. If only one is provided, the Checker* will land on that challenge*.

Redirect URI parameter

It is recommended to URL-encode this parameter.

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

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.

https://www.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

Example

The website opens a new window to:

http

https://www.ageverif.com/oauth2/checker
  ?client_id=V61LHMuuwahgYDcGnagso
  &redirect_uri=https%3A%2F%2Fwww.example.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://www.example.org/oauth2-callback
  ?code=8f0FwyzmlDSfdOiEaTjxJPXBeBEfCYrvkLyrHoM3DRZMvbaiBciebOgKfKjwWCwk
  &state=abc123

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

2. Token

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

http

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

Headers

Field	Type	Format	Description
Authorization	string	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	`authorization_code`	Provided authorization grant type. Only `authorization_code` is available at the moment
code	string	E.g. `8f0FwyzmlDSfdOiE...`	Authorization grant code returned from previous step
redirect_uri	string	E.g. `https://www.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.

Response

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

Content-Type: application/json

{
  "token_type": "Bearer",
  "access_token": [access_token],
  "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_in	int	E.g. `3600`	Seconds until token expires

Example

The website sends a request with the code obtained in the previous step to the Token endpoint:

bash

curl -X POST https://www.ageverif.com/api/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://www.example.org/oauth2-callback" \

Response:

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

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

3. Resources (optional)

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

http

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

Obtaining "resources" is optional

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

The only visitor resource available is verified.

This endpoint exists to comply with the OAuth2 specification and to allow for future resources.

Headers

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

Parameters

Field	Type	Format	Description
resources	array(string) (optional)	`verified`	Array with visitor resources to return. Only `verified` available

Response

{
  "resources": [resources]
}

Field	Type	Format	Description
resources	array(key, value)	E.g. `{"verified": true}`	Requested resources

Example

The website sends a request to the Resources endpoint with the access_token obtained in the previous step:

bash

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

Response:

{
  "resources": { "verified": true }
}

Integrations

JavaScript API (ageverif)

Examples

OAuth2 API

Requirements

Flow 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 (optional)

Headers

Parameters

Response

Example

OAuth2 API ​

Requirements ​

Flow 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 (optional) ​

Headers ​

Parameters ​

Response ​

Example ​

OAuth2 API

Requirements

Flow 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 (optional)

Headers

Parameters

Response

Example