OAuth2

SDK

We provide a PHP SDK with an example integration to make it easier and faster to get ready to verify your customers' age:

VerifyMyAge Adult PHP SDK

Postman Workspace

We've created a Postman workspace specifically for our API, which contains example API calls that you can use to test and familiarise yourself with our API.

The workspace includes example API calls for each of our API endpoints, along with detailed descriptions of the request parameters and headers being used.

You can generate most of the client code to call our APIs using the Postman client code generator. With this feature, developers can select a range of programming languages, and generate the corresponding code with a few clicks.

Please note that while both the example API calls and the generated code can be a helpful starting point, it's important to thoroughly test your own API calls before deploying them in production. If you encounter any issues while using the example API calls, or if you have any questions about our API, please don't hesitate to reach out to our support team.

API Domain

Our API is designed to be used in two environments: a sandbox environment and a production environment.

The sandbox environment is intended for testing and development purposes, while the production environment is used for live data and real-world use cases.

To ensure the security and integrity of our API, we use separate API keys for each environment. This means that you will need to obtain different API keys for the sandbox and production environments, and should not use the same key for both.

Domain	Environment
https://oauth.verifymyage.com	production
https://sandbox.verifymyage.com	sandbox

User Journey

Each country has different requirements for accessing adult content which are laid out by the regulator of that country.

A user is required to verify their age the first time they visit your site. They simply log in to their VerifyMyAge account for future sessions.

Integration Steps

The OAuth2 verification consists of 2 basic steps, getting a user access token and then getting user data:

1. Redirect the user to the VerifyMyAge verification flow

2. Your server performs a POST request to exchange the code for an access_token

Then, you can confirm that the user is age-verified by calling the user details endpoint using the access_token received.

Redirect user to the flow

This will redirect the user back to the URL you've sent on the redirect_uri query parameter with one key extra query parameter code. This value sent will be used on the next step of the OAuth2 flow.

Request parameters

client_id required

Your API Key which can be found in your VerifyMyAge dashboard.

scope required

Constant value must be set as adult.

redirect_uri required

URL that the user will be redirected to after the age-verification flow.

country required

2-letter ISO country code. Available options: gb, de, fr, or us.

Note: Additional options are available. Please contact us to discuss this further.

user_id optional

User's unique ID.

Error responses

Code	Description
400	`{"message": "invalid client id", "status_code": 400}` Copied!
400	`{"message": "invalid params","status_code": 400}` Copied!
400	`{"message": "invalid scope","status_code": 400}` Copied!
401	`{"message": "Unauthorized redirect_uri","status_code": 401}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl php

GET /oauth/authorize?client_id=CLIENT-ID&scope=adult&country=gb&redirect_uri=https://your-domain.com/your-path HTTP/1.1

Copied!

curl https://sandbox.verifymyage.com/oauth/authorize?client_id=CLIENT-ID&scope=adult&country=gb&redirect_uri=https://your-domain.com/your-path

Copied!

<?php
require(__DIR__ . "/vendor/autoload.php");

use \VerifyMyAge\OAuth;
use \VerifyMyAge\Countries;


$redirectURL = $vma->redirectURL(Countries::FRANCE);

Copied!

Response 302

Exchange code by token

For security reasons, you'll have to send your secret key via server-side to exchange the code for an access_token.

Following the OAuth2 standard, you'll have to send the Authorization header using the Basic authentication format:

The value is generated by the base64 string of the concatenation of your API Key and API Secret separated by a colon (:).

Example in PHP:

[
    'Authorization' => 'Basic ' . base64_encode(
        $apiKey . ':' . $apiSecret
    )
]

Request parameters

code required

The code received as a query parameter to your redirect_uri in the previous step.

Error responses

Code	Description
400	`{"message": "invalid client credentials", "status_code": 400}` Copied!
401	`{"message": "client id and client secret does not match","status_code": 401}` Copied!
401	`{"message": "Unauthorized redirect_uri","status_code": 401}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl php

POST /oauth/token HTTP/1.1
Content-Type: application/json
Authorization: Basic {BASE64}

{
    "code": "CODE-RECEIVED-ON-THE-FIRST-STEP"
}

Copied!

curl -d '{"code": "CODE-RECEIVED-ON-THE-FIRST-STEP"}' \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic {BASE64}" \
    -X POST https://sandbox.verifymyage.com/oauth/token

Copied!

<?php
require(__DIR__ . "/vendor/autoload.php");

use \VerifyMyAge\OAuth;
use \VerifyMyAge\Countries;

$accessToken = $vma->exchangeCodeByToken($_GET['code']);

Copied!

Response 200: (application/json)

{
  "access_token": "RANDOM-CODE"
}

Copied!

User details

You are able to get the status of the verification now.

Request parameters

access_token required

The token generated by VerifyMyAge in Step 2.

Response parameters

age_verified

Boolean that represents whether the user completed the process or not.

Value	Description
true	The user has completed the verification process successfully.
false	The user has not completed the verification process successfully

Unique Identifier representing a verification.

threshold

The age threshold the user has to meet. It is a fixed value of 18.

Error responses

Code	Description
400	`{"message": "malformed token", "status_code": 400}` Copied!
500	`{"message": "error trying to save verification","status_code": 500}` Copied!
500	`{"message": "invalid scope to present","status_code": 500}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl php

GET /users/me?access_token={TOKEN} HTTP/1.1

Copied!

curl https://sandbox.verifymyage.com/users/me?access_token={TOKEN}

Copied!

<?php
require(__DIR__ . "/vendor/autoload.php");

use \VerifyMyAge\OAuth;
use \VerifyMyAge\Countries;

$user = $vma->user($accessToken);

Copied!

Response 200: (application/json)

{
  "age_verified": true,
  "id": "ABC-12345-DEF-64321",
  "threshold": 18
}

Copied!

Allowed Redirect URLs

URLs that are allowed to be redirected to after a successful verification.

Generating the HMAC header

To improve the security of the communication between your implementation and the VerifyMyAge API, we require you to generate a unique hexadecimal encoded SHA256 HMAC hash for each request, based on the input parameters.

The process of generating it depends on the language of your implementation.

Example

php node.js python go

<?php

hash_hmac('sha256', $input, 'API_SECRET');

Copied!

import { HmacSHA256 } from 'crypto-js';

HmacSHA256(JSON.stringify(input), 'API_SECRET').toString()

Copied!

import hmac
import hashlib

def generateAuthHmacHeader(api_key, api_secret, request_body):
    sign_bytes = hmac.new(api_secret.encode('utf-8'), request_body.encode('utf-8'), hashlib.sha256).digest()
    sign_hex = sign_bytes.hex()
    authorization_header = f"hmac {api_key}:{sign_hex}"
    return authorization_header

Copied!

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
)

func generateAuthHmacHeader(apiKey, apiSecret, requestBody []byte]) string {
    hmac := hmac.New(sha256.New, []byte(apiSecret))
    h.Write(requestBody)

    signBytes := h.Sum(nil)

    signHex := hex.EncodeToString(signBytes)
    authorizationHeader := fmt.Sprintf("hmac %s:%s", apiKey, signHex)
    return authorizationHeader
}

Copied!

Get allowed URLs

Retrieve a list of allowed redirect URLs.

Authorization Header

Generate HMAC with: Request URI
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Response parameters

body

The list of Allowed Redirect URLs.

Error responses

Code	Description
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl

GET /v1/business/allowed-redirects HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI

Copied!

curl https://sandbox.verifymyage.com/v1/business/allowed-redirects
    --header 'Content-Type: application/json'
    --header 'Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-URI'

Copied!

Response 200: (application/json)

{
  "body": [
    "https://your-website.com/redirect-1",
    "https://your-website.com/redirect-2"
  ]
}

Copied!

Add Allowed URLs

Add one or more allowed redirect URLs.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

body required

An array containing the allowed redirect URLs.

Error responses

Code	Description
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl

PATCH /v1/business/allowed-redirects HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY
[
    "https://your-website.com/redirect-1"
]

Copied!

curl -X PATCH https://sandbox.verifymyage.com/v1/business/allowed-redirects
    --header 'Content-Type: application/json'
    --header 'Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY'
    --data '[
    "https://your-website.com/redirect-1"
]'

Copied!

Response 204

Replace All Allowed URLs

Replace any existing allowed redirect URLs with the provided list.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

body required

An array containing the allowed redirect URLs.

Error responses

Code	Description
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl

PUT /v1/business/allowed-redirects HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY
[
    "https://your-website.com/new-redirect-url"
]

Copied!

curl -X PUT https://sandbox.verifymyage.com/v1/business/allowed-redirects
    --header 'Content-Type: application/json'
    --header 'hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY'
    --data '[
    "https://your-website.com/new-redirect-url"
]'

Copied!

Response 204

Delete Allowed URLs

Remove one or more allowed redirect URLs.

Authorization Header

Generate HMAC with: Request Body
Authorization: hmac YOUR-API-KEY:GENERATED-HMAC

Request parameters

body required

An array containing the allowed redirect URLs.

Error responses

Code	Description
401	`{"message": "invalid authentication", "status_code": 401}` Copied!
500	`{"message": "Internal Server Error","status_code": 500}` Copied!

API Call

http curl

DELETE /v1/business/allowed-redirects HTTP/1.1
Content-Type: application/json
Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY
[
    "https://your-website.com/redirect-1",
    "https://your-website.com/redirect-2"
]

Copied!

curl -X DELETE https://sandbox.verifymyage.com/v1/business/allowed-redirects
    --header 'Content-Type: application/json'
    --header 'Authorization: hmac YOUR-API-KEY:GENERATE-HMAC-WITH-REQUEST-BODY'
    --data '[
    "https://your-website.com/redirect-1",
    "https://your-website.com/redirect-2"
]'

Copied!

Response 204

Demo

You can try a demo of this integration at:

https://demo.verifymyage.com/

OAuth2

SDK​

Postman Workspace

API Domain

User Journey​

Integration Steps​

Redirect user to the flow​

Request parameters

Error responses

Exchange code by token​

Request parameters

Error responses

User details​

Request parameters

Response parameters

Error responses

Allowed Redirect URLs​

Generating the HMAC header

Get allowed URLs​

Authorization Header

Response parameters

Error responses

Add Allowed URLs​

Authorization Header

Request parameters

Error responses

Replace All Allowed URLs​

Authorization Header

Request parameters

Error responses

Delete Allowed URLs​

Authorization Header

Request parameters

Error responses

Demo​

SDK

User Journey

Integration Steps

Redirect user to the flow

Exchange code by token

User details

Allowed Redirect URLs

Get allowed URLs

Add Allowed URLs

Replace All Allowed URLs

Delete Allowed URLs

Demo