Webmaster External API

The Webmaster External API allows webmasters to programmatically interact with AgeVerif services.

Requirements

• Be registered on our Webmasters Platform as a webmaster, available at https://webmasters.ageverif.com.
• Be familiar with RESTful API concepts and HTTP methods (GET, POST, PATCH).

Authentication

All requests to the Webmaster External API must be authenticated using a Bearer token.

Include your token in the request headers as follows:

Authorization: Bearer YOUR_API_KEY

Creating token

1. Log in to your account on the Webmasters Platform.
2. Navigate to the "Account" section in the sidebar menu.
3. Under the "Authorization Token" section, click on "Generate".
4. Copy your new token.

Endpoints

1. Website - create, retrieve and update websites.
2. OAuth2 - create, retrieve and update OAuth2 for registered websites.

Website

Parameter	Description
website_id	The unique identifier of the website.
environment	The environment for the website keys. Can be either live or test.

Create website

POST https://webmasters-api.ageverif.com/external/website

Description: Register a new website.

Request Body:

Content-Type: application/json

Field	Description
name	Your website name.
domain	Your website domain.
language	(optional) Forces a given language. Auto is based on the visitor's browser language, with fallback to en if not available. Default: auto
challenges	(optional) Loads only the given challenges. Default: all free challenges
regions	(optional) E.g. ["KW", "US-AL"] Available: all ISO 3166-1 alpha-2 country codes. For the US, ISO 3166-2 subdivision codes are supported (e.g., US-AL) Default: triggers verification in all regions.

interface Request {
    name: string;
    domain: string;
    language?: 'auto' | 'de' | 'en' | 'es' | 'fr' | 'it' | 'pt';
    challenges?: (`selfie` | `email_age` | `credit_card` | `ticket` | `anonymage` | `pleenk`)[];
    regions?: string[];
}

Note: The response is equivalent to the one in “Retrieve website” endpoint.

Update website

PATCH https://webmasters-api.ageverif.com/external/website/{website_id}

Description: Update details of a registered website.

Request Body:

Content-Type: application/json

Field	Description
name	Your website name.
language	(optional) Forces a given language. Auto is based on the visitor's browser language, with fallback to en if not available. Default: auto
challenges	(optional) Loads only the given challenges. Default: all free challenges
regions	(optional) E.g. ["KW", "US-AL"] Available: all ISO 3166-1 alpha-2 country codes. For the US, ISO 3166-2 subdivision codes are supported (e.g., US-AL) Default: triggers verification in all regions.

interface Request {
    name?: string;
    language?: 'auto' | 'de' | 'en' | 'es' | 'fr' | 'it' | 'pt';
    challenges?: (`selfie` | `email_age` | `credit_card` | `ticket` | `anonymage` | `pleenk`)[];
    regions?: string[];
}

Important:

• name, language, challenges and regions are optional fields.
• However, at least one of these fields must be included in the request.

Note: The response is equivalent to the one in “Retrieve website” endpoint.

Retrieve website

GET https://webmasters-api.ageverif.com/external/website/{website_id}

Description: Retrieve details of a registered website.

Response Fields:

Content-Type: application/json

Field	Description
id	Unique website id.
name	Your website name.
domain	Your website domain.
language	The language set for the website.
regions	The regions set for the website. All ISO 3166-1 alpha-2 country codes. For the US, ISO 3166-2 subdivision codes are supported (e.g., US-AL)
challenges	The challenges set for the website.
keys	The public keys for the website in different environments.

interface Response {
    id: number;
    name: string;
    domain: string;
    language: 'auto' | 'de' | 'en' | 'es' | 'fr' | 'it' | 'pt';
    regions: string[]; // ISO 3166-1 alpha-2 country codes, with support for ISO 3166-2 subdivision codes for the US (e.g., US-AL)
    challenges: (`selfie` | `email_age` | `credit_card` | `ticket` | `anonymage` | `pleenk`)[];
    keys: {
        environment: 'LIVE' | 'TEST';
        publicKey: string;
    }[];
}

Regenerate website keys

PATCH https://webmasters-api.ageverif.com/external/website/{website_id}/key/{environment}/regenerate

Description: Regenerate the public/private key pair for a registered website.

Response Fields:

Content-Type: application/json

Field	Description
environment	The environment for the key pair.
publicKey	The new public key for the website.

interface Response {
    environment: 'LIVE' | 'TEST';
    publicKey: string;
}

Retrieve website keys

GET https://webmasters-api.ageverif.com/external/website/{website_id}/key/{environment}

Description: Retrieve the public key for a registered website.

Response Fields:

Content-Type: application/json

Field	Description
environment	The environment for the key pair.
publicKey	The public key for the website.

interface Response {
    environment: 'LIVE' | 'TEST';
    publicKey: string;
}

OAuth2

Parameter	Description
website_id	The unique identifier of the website.
environment	The environment for the OAuth2 configuration. Can be either live or test.

Create OAuth2

POST https://webmasters-api.ageverif.com/external/website/{website_id}/oauth2/{environment}

Description: Create a new OAuth2 for a registered website.

Request Body:

Content-Type: application/json

Field	Description
redirectUris	List of allowed redirect URIs.

interface Request {
    redirectUris: string[];
}

Note: The response is equivalent to the one in “Retrieve OAuth2 ” endpoint.

Update OAuth2

PATCH https://webmasters-api.ageverif.com/external/website/{website_id}/oauth2/{environment}

Description: Update an existing OAuth2 for a registered website.

Request Body:

Content-Type: application/json

Field	Description
redirectUris	List of allowed redirect URIs. This field will be ignored if the status is set to DISABLED.
status	The status to assign to the OAuth2

interface Request {
    redirectUris?: string[];
    status?: 'ACTIVE' | 'DISABLED';
}

Important:

• redirectUris and status are optional fields.
• However, at least one of these fields must be included in the request.

Note: The response is equivalent to the one in “Retrieve OAuth2” endpoint.

Regenerate OAuth2 Client id/Secret

PATCH https://webmasters-api.ageverif.com/external/website/{website_id}/oauth2/{environment}/regenerate

Description: Regenerate the client id and secret for an existing OAuth2 of a registered website.

Important:

• OAuth2 status needs to be ACTIVE to regenerate the client secret.
• The new key takes effect immediately, and the previous key stays valid for 24 hours to allow for a smooth transition.
• if regenerate again within 24 hours, the previous key will be invalidated immediately.

Note: The response is equivalent to the one in “Retrieve OAuth2” endpoint.

Retrieve OAuth2

GET https://webmasters-api.ageverif.com/external/website/{website_id}/oauth2/{environment}

Description: Retrieve a specific OAuth2 for a registered website.

Response Fields:

Content-Type: application/json

Field	Description
environment	The environment for which the OAuth2 is created.
redirectUris	List of allowed redirect URIs.
status	The current status of the OAuth2.
clientId	Unique identifier for the OAuth2, Returned only if status = ACTIVE.
clientSecret	Secret key for the OAuth2, Returned only if status = ACTIVE.

interface Response {
    environment: 'LIVE' | 'TEST';
    redirectUris: string[];
    status: 'ACTIVE' | 'DISABLED';
    clientId?: string;
    clientSecret?: string;
};

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request. Common status codes include:

• 200 OK: The request was successful.
• 400 Bad Request: The request was invalid or cannot be served.
• 401 Unauthorized: Authentication failed or webmaster does not have permissions for the requested operation.
• 404 Not Found: The requested resource could not be found.
• 500 Internal Server Error: An error occurred on the server.

Response for Errors:

Content-Type: application/json

interface ErrorResponse {
    message: string;      // A descriptive error message
    error: string;        // The type of error
    statusCode: number;   // The HTTP status code
}

{
    "message": "Invalid token",
    "error": "Unauthorized",
    "statusCode": 401
}