S2S Integration

The Server-to-Server (S2S) integration allows your backend to fully control when and how users are sent to AgeGO for age verification.

This integration does not require any frontend code and is ideal if you want to manage age verification entirely from your server-side logic, including routing, session handling, and access control.

When to Use S2S Integration

S2S is recommended if you:

• Want full backend control over the verification flow.
• Prefer redirects over frontend modals.
• Already manage user sessions and access logic server-side.
• Need a clear separation between your frontend and verification logic.

High-Level Flow

At a high level, the S2S integration works as follows:

1. Your backend determines that a visitor requires age verification.
2. Your server redirects the user to AgeGO for verification.
3. The user completes the configured verification checks on AgeGO.
4. AgeGO redirects the user back to your site.
5. Your backend validates the response and grants or denies access accordingly.

Prerequisites

Before implementing S2S integration, ensure you have:

• An active AgeGO site configured in the dashboard (Name, Website URL, Callback URL, Site Status).
• Your asi.
• An HTTPS endpoint on your side to receive the user after verification.

Get Your S2S Start URL

Each AgeGO site has a unique S2S start URL available in the dashboard.

Redirecting the User to AgeGO

When your website determines that a user must be age verified (for example, on first visit or before accessing restricted content), your backend redirects the user to the AgeGO S2S start URL.

This redirect URL is unique per site and supports several query parameters to control security, routing, and user experience.

Redirect Parameters

• asi (mandatory): The unique identifier of your site in AgeGO. This value links the verification request to the correct site configuration.
• returnto (optional, recommended): Defines the HTTPS URL where the user is redirected after the age-verification flow completes.

  • When provided, AgeGO redirects the user to this URL after verification.
  • When omitted, AgeGO redirects the user to the root of your Site’s Website URL.
  • When used, this must be a full HTTPS URL pointing to a specific page on your domain.

Using returnto is strongly recommended to maintain control over post-verification routing.

Example with returnto :

https://.../start?asi=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&returnto=https%3A%2F%2Fwww.example.com%2Fmembers%2Fwelcome

Without returnto (falls back to Site’s Website URL root):

https://.../start?asi=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

• nonce: Optional, a random hexadecimal value that will be sent in return request to prevent session tampering and sharing. This value can be saved with user session and used later to verify the returning visitor has the same session. nonce MUST be 64 characters or less.
• callbacktoken: Optional, value that will be replaced in the site callback url {callbacktoken}. callbacktoken MUST be 64 characters or less.
• redirect: The redirect parameter controls which page the user is sent to when the flow starts. The following values are supported:

  • myaccount: When set to myaccount, the user is redirected to the My Account page after logging in.

    • If the user is already logged in, they are taken directly to My Account.
    • If the user is not logged in, they are first sent to the login page. After logging in, the flow proceeds to My Account.
    • Verification logic remains unchanged:

      • If the user is not verified, they are redirected to the Verification Methods page.
      • If the user is verified, they proceed normally.
  • login: When set to login, the user is redirected directly to the login page instead of the usual starting page of the flow. After logging in:

    • If the user is not verified, they are sent to the Verification Methods page.
    • If the user is verified, they continue through the standard flow.
  • Default value: If no value is provided, the user lands on the default starting page of the flow.

Important Notes

• Redirect parameters apply only to the Server-to-Server (S2S) integration.
• The hostname used in returnto must be whitelisted in your site settings.
• Redirect behavior in S2S differs from the Modal integration.

Example redirect URL:

https://myapi.agego.com/s2s/start/?asi=YOUR_ASI&returnto=YOUR_RETURN_URL&nonce=OPTIONAL_RANDOM_VALUE&callbacktoken=OPTIONAL_RANDOM_VALUE&redirect=myaccount

After verification, the user is redirected back to:

• the URL specified in returnto (if provided), or
• the root of your site’s Website URL.

Your backend should:

• Parse the returned query or fragment parameters.
• Verify the integrity of the response (ag_signature).
• Validate the nonce (if used).
• Map the result to the correct user or session.
• Grant or deny access accordingly.

Return Parameters

The redirect back to your site includes the following GET parameters describing the verification result:

• ag_error: Error code, if any (see below for possible error codes).
• ag_expires: UNIX timestamp in milliseconds after which this request must be considered as expired.
• ag_nonce: Value initially sent with nonce parameter in redirect url, none if no value was sent.
• ag_verified: Yes if the visitor was successfully age-verified, no otherwise.
• ag_verified_site: unique id of the website the visitor was verified for, must match the id of the site for the asi parameter in the initial request.
• ag_user_token: a unique token identifying the verified user.

In addition to above, the following two parameters are sent to verify the information sent with the redirect has not been tampered with and is in fact sent by AgeGO platform.

• ag_signature: Checksum of all the values of the previously listed GET parameters.
• ag_signature_algo: Hash algorithm used for the signature. Currently, the only possible value for this parameter is sha256, however, in future, a different algorithm might be used - all users will be notified about any signing algorithm changes in advance.

Other optional parameters that might or might not be present in return request:

• ag_remember_me: Optional, values yes, or no. Indicates strong user preference to persist the verification result beyond normal session lifetime. Value yes indicates user prefers to persist verification status beyond session lifetime, ex. for 1 year.

Overlay S2S Mode

Enables server-to-server (S2S) verification mode. When set to true, the AgeGO prompt expects age verification results to be provided via URL query parameters (such as ag_user_token and ag_verified, or ag_token).

It is intended for use cases where verification is handled externally and the result is returned to the frontend, typically through cross-site verification flows or post verification redirects.

If valid parameters are present, the user is considered verified, the agego_aver cookie is set with the values from the query parameters, and no overlay or modal is ever shown.

Both ag_user_token (with ag_verified=yes) and ag_token are supported for verification in this mode.

⚠️ It is not required for standard S2S integrations and should only be used when verification results are returned to the frontend.

<!-- AgeGO Age verification -->
<script src="https://verifycdn.agego.com/v2/verify.js"></script>
<script>
  window.AGEGO = window.AGEGO || function () {
    (AGEGO.e = AGEGO.e || []).push(arguments);
  };

  AGEGO('init', {
    s2sMode: true,
    // ... other options
  });
  AGEGO('launch');
</script>

Note: If you also need to share the agego_aver cookie across subdomains while using s2sMode, the same domain configuration described in Modal Integration → Cookie Options applies.

Verifying the Signature

All return requests will always be accompanied with ag_signature parameter that contains a keyed hash value using HMAC hashing method.

The hash is computed on all values in return request listed below, separated by vertical bar, and in the exact order as specified below:

ag_error | ag_expires | ag_nonce | ag_verified | ag_verified_site

The secret used to calculate the HMAC can be found in "My Sites" section for each individual site.

Important Security Checks

• Always verify if ag_signature_algo contains the permitted value(s) as documented above.
• A string none is used to indicated default/missing values, for example, for ag_nonce, ag_error and similar.
• Always verify that ag_expires timestamp value is in the future.
• Using nonce is not mandatory but is recommended to prevent sharing of the verification URL.
• Keep your site secret value private and not accessible in frontend code. Leaked site secret will allow for anyone to impersonate age verification responses and bypass the verification process.

Possible Error Codes

• none: Indicates no error.
• suspended: The site is suspended or has run out of credits.

Code Examples for Signature Calculation

Minimal code examples to illustrated signature verification process of the return request.

PHP

$data = sprintf(
    '%s|%s|%s|%s|%s',
    $query['ag_error'],
    $query['ag_expires'],
    $query['ag_nonce'],
    $query['ag_verified'],
    $query['ag_verified_site']
);

$expectedSignature = hash_hmac('sha256', $data, $siteSecret);

$status = $query['ag_signature'] === $expectedSignature;

// TODO: check if $status === true

Python

import hmac
import hashlib

if query.ag_signature_algo == 'sha256':
    algo = hashlib.sha256
else:
    raise Exception('Invalid hash algorithm')

data = '%s|%s|%s|%s|%s' % (
    query.ag_error,
    query.ag_expires,
    query.ag_nonce,
    query.ag_verified,
    query.ag_verified_site
)

status = hmac.new(site_secret, data, algo).hexdigest() == query.ag_signature

# TODO: check if status == True

NodeJs

const crypto = require('crypto');

const data =
  query['ag_error'] + '|' +
  query['ag_expires'] + '|' +
  query['ag_nonce'] + '|' +
  query['ag_verified'] + '|' +
  query['ag_verified_site']
;

const hmac = crypto.createHmac(signatureAlgo, siteSecret);
hmac.update(data);
const status = hmac.digest('hex') === query['ag_signature'];

// TODO: check if status === true

Ruby

require 'openssl'

data = "#{query['ag_error']}|" \
       "#{query['ag_expires']}|" \
       "#{query['ag_nonce']}|" \
       "#{query['ag_verified']}|" \
       "#{query['ag_verified_site']}"

digest = OpenSSL::Digest.new(signature_algo)

status = OpenSSL::HMAC.hexdigest(digest, site_secret, data) == signature

# TODO: check if status === true

Validating ag_user_token with the AgeGO API

POST https://myapi.agego.com/authorization/user/validate-token

Use the ag_user_token returned by the S2S callback as the value of token.

Request body (JSON)

Parameter	Required	Description
token	Yes	JWT returned after successful verification.
country	Optional	ISO 3166-1 alpha-2 country code (e.g. "DE").
region	Optional	ISO 3166-2 subdivision code without the country prefix (e.g. "FL" for Florida/US) — Requires country

When country is provided (optionally with region), the token is also validated against the user's verification methods for that location.

Call this endpoint when a returning verified user accesses your site and you need to confirm the token is still valid for their current location.

Publishers must not replicate AgeGO's location-validity logic on their side. All location-eligibility checks must go through this endpoint.

Responses

Status	Response Body	Description
200	{ "status": true, "message": "Valid token" }	Token is valid. When country is provided, the verification methods are also accepted for that location
200	{ "status": false, "error": "..." }	Where "..." is one of: Invalid token — signature invalid or token expired Invalid token structure — token is missing required claims User invalid — the user was not found, has logged out or been deleted No valid verification method for country/region — verification method isn't accepted in the supplied location
400	{ "status": false, "error": "..." }	Where "..." is one of: No token provided — The request is malformed (missing token) Country is required when region is provided — region supplied without country.
500	{ "status": false, "error": "Validation failed" }	Server error during validation

Code Examples for Validating ag_user_token with the AgeGO API

Minimal code examples to illustrate user token validation process using AgeGO API.

PHP

$url = 'https://myapi.agego.com/authorization/user/validate-token';
$token = 'your-jwt-token-here';

$data = json_encode([
'token' => $token,
'country' => 'DE', // optional
'region' => 'BY'   // optional
]);

$ch = curl_init();

curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $data,
CURLOPT_HTTPHEADER => [
  'Content-Type: application/json',
  'Content-Length: ' . strlen($data)
],
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

echo "HTTP Code: $httpCode\n";
echo "Response: $response\n";

$decodedResponse = json_decode($response, true);
if ($decodedResponse['status']) {
  echo "Token is valid\n";
} else {
  echo "Token validation failed: " . $decodedResponse['error'] . "\n";
}

curl_close($ch);

NodeJs

const https = require('https');

const url = 'https://myapi.agego.com/authorization/user/validate-token';
const token = 'your-jwt-token-here';

const data = JSON.stringify({
token: token,
country: 'DE', // optional
region: 'BY'   // optional
});

const options = {
method: 'POST',
headers: {
  'Content-Type': 'application/json',
  'Content-Length': Buffer.byteLength(data)
}
};

const req = https.request(url, options, (res) => {
let responseData = '';

res.on('data', (chunk) => {
  responseData += chunk;
});

res.on('end', () => {
console.log(`HTTP Code: ${res.statusCode}`);
console.log(`Response: ${responseData}`);

try {
  const decodedResponse = JSON.parse(responseData);
  if (decodedResponse.status) {
    console.log('Token is valid');
  } else {
    console.log('Token validation failed');
  }
} catch (error) {
  console.log('Error parsing response:', error.message);
}
});
});

req.write(data);
req.end();