DocsVerify tokens
Verify tokens on your server
PlannedThe token is a signed JWT. Your server checks the signature with Ageseal public keys and reads a few claims. No call to Ageseal is needed, unless you want strict single use.
The token
A compact JWS with the header { "alg": "ES256", "typ": "JWT", "kid": "<key id>" }. The payload of a live token looks like this:
{
"iss": "https://api.ageseal.eu",
"aud": "site_7Kq2",
"over": 18,
"result": true,
"method": "mdoc",
"mode": "live",
"iat": 1795000000,
"exp": 1795000600,
"jti": "Kq1v0nS3m9rXb2Z4pYw8dA"
}Claims
| Claim | Value | What to do |
|---|---|---|
iss | https://api.ageseal.eu for live, https://api.ageseal.eu/test for test | Must match the live value exactly in production. |
aud | Your site id, as shown in the dashboard. Test tokens have test: before it | Must equal your site id. This stops a token made for another site, or a test token, from working on yours. |
over | 16, 18 or 21 | Must be at least the age you require. |
result | true or false | Must be true. A visitor under the threshold gets a valid token with false. |
method | mdoc | For your records. sd-jwt is reserved and not implemented. |
mode | test or live | Must be live in production. A test token already fails the iss and aud checks, but check mode as well. |
iat, exp | Unix seconds. exp is 10 minutes after iat | Reject expired tokens. Allow a little clock skew, for example 30 seconds. |
jti | A random token id | Never a person id. Use it for your own single use bookkeeping, or let redeem do it. |
There is no sub, no issuer name, no country and no document data in the token.
Verification steps
- Read the
kidfrom the token header and pick that key from the public key set. - Check the ES256 signature. Accept only
ES256, never the algorithm the token asks for. - Check
iss,audandexpagainst the live values. - Check
resultistrue,overis high enough, andmodeislivein production. - Let the visitor in, and remember that on your side. Do not ask for a new token on every page.
Examples
Each example is a complete check of a live token. Replace the site id with yours.
import { createRemoteJWKSet, jwtVerify } from "jose"; // npm install jose
const jwks = createRemoteJWKSet(new URL("https://api.ageseal.eu/.well-known/jwks.json"));
export async function isOver18(token) {
try {
const { payload } = await jwtVerify(token, jwks, {
issuer: "https://api.ageseal.eu",
audience: process.env.AGESEAL_SITE_ID, // "site_7Kq2"
algorithms: ["ES256"],
});
return payload.result === true && payload.over >= 18 && payload.mode === "live";
} catch {
return false; // bad signature, wrong site, expired ...
}
}
// POST /age-ok
export async function POST(request) {
const token = await request.text();
if (!(await isOver18(token))) return new Response("Not verified", { status: 403 });
// Remember it on your side, for example in your session, then let the visitor in.
return new Response("OK");
}package ageseal
// go get github.com/MicahParks/keyfunc/v3 github.com/golang-jwt/jwt/v5
import (
"os"
"github.com/MicahParks/keyfunc/v3"
"github.com/golang-jwt/jwt/v5"
)
var jwks, _ = keyfunc.NewDefault([]string{"https://api.ageseal.eu/.well-known/jwks.json"})
func IsOver18(token string) bool {
t, err := jwt.Parse(token, jwks.Keyfunc,
jwt.WithValidMethods([]string{"ES256"}),
jwt.WithIssuer("https://api.ageseal.eu"),
jwt.WithAudience(os.Getenv("AGESEAL_SITE_ID")), // "site_7Kq2"
jwt.WithExpirationRequired(),
)
if err != nil {
return false
}
c, ok := t.Claims.(jwt.MapClaims)
if !ok {
return false
}
over, _ := c["over"].(float64)
return c["result"] == true && over >= 18 && c["mode"] == "live"
}<?php
// composer require firebase/php-jwt
use Firebase\JWT\JWK;
use Firebase\JWT\JWT;
function isOver18(string $token): bool {
// Cache this for a few minutes, for example in APCu or a file.
$jwks = json_decode(file_get_contents('https://api.ageseal.eu/.well-known/jwks.json'), true);
try {
$c = JWT::decode($token, JWK::parseKeySet($jwks, 'ES256'));
} catch (Throwable $e) {
return false; // bad signature, expired ...
}
return $c->iss === 'https://api.ageseal.eu'
&& $c->aud === getenv('AGESEAL_SITE_ID') // 'site_7Kq2'
&& $c->result === true
&& $c->over >= 18
&& $c->mode === 'live';
}import os
import jwt # pip install "pyjwt[crypto]"
jwks = jwt.PyJWKClient("https://api.ageseal.eu/.well-known/jwks.json")
def is_over_18(token: str) -> bool:
try:
key = jwks.get_signing_key_from_jwt(token)
c = jwt.decode(
token,
key.key,
algorithms=["ES256"],
issuer="https://api.ageseal.eu",
audience=os.environ["AGESEAL_SITE_ID"], # "site_7Kq2"
options={"require": ["exp", "iat", "iss", "aud"]},
)
except jwt.PyJWTError:
return False # bad signature, wrong site, expired ...
return c["result"] is True and c["over"] >= 18 and c["mode"] == "live"Test tokens
A token from a test key differs from a live token in three claims, not only in mode: iss is https://api.ageseal.eu/test, aud is test: followed by your site id, and mode is test. The signature uses the same public keys.
- A server that checks
issandaudthe way the examples above do refuses every test token, even if it forgets to checkmode. - Anyone can make a test token that says pass, because test keys accept credentials from a public test issuer. Treat a test token as proof of nothing.
- To try your integration with a test key, run the same check with the test values on your staging server. Choose the values from configuration, and never accept both sets in one check.
// Staging only. Production uses the live values from the examples above.
const { payload } = await jwtVerify(token, jwks, {
issuer: "https://api.ageseal.eu/test",
audience: "test:" + process.env.AGESEAL_SITE_ID, // "test:site_7Kq2"
algorithms: ["ES256"],
});
const ok = payload.result === true && payload.over >= 18 && payload.mode === "test";Public keys
The key set is at https://api.ageseal.eu/.well-known/jwks.json. It is a standard JWK set of P-256 keys, each with kty, crv, x, y, kid, use: "sig" and alg: "ES256". The response is public, allows any origin and is cached for 5 minutes.
- Cache the key set in your server for a few minutes. Do not fetch it on every request.
- When a token has a
kidyou do not know, fetch the key set again once, then decide. Do this at most once a minute, so a bad token cannot make you hammer the endpoint. - Never copy a public key into your code. Keys rotate.
Key rotation
Ageseal publishes the new key before it signs with it, and keeps the old key published until old tokens have expired. The planned order is: publish the new key, wait at least an hour, switch signing to it, and remove the old key after another 15 minutes. If you follow the kid rule above, you never need to do anything.
Single use redemption
Offline verification proves a token is genuine, but the same token can be shown again until it expires. If you need each token to count once, redeem it from your server with your secret key. Ageseal checks the signature, iss, exp, aud and mode, stores the jti until exp, and rejects a second redeem. A test secret key redeems test tokens only, and a live secret key live tokens only.
curl -X POST https://api.ageseal.eu/v1/tokens/redeem \
-H "Authorization: Bearer $AGESEAL_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "token": "eyJ..." }'export async function redeem(token) {
const res = await fetch("https://api.ageseal.eu/v1/tokens/redeem", {
method: "POST",
headers: {
authorization: `Bearer ${process.env.AGESEAL_SECRET_KEY}`, // "sk_test_Hn4x"
"content-type": "application/json",
},
body: JSON.stringify({ token }),
});
if (res.status === 409) return false; // token_already_redeemed
if (!res.ok) throw new Error("redeem failed: " + res.status);
const { valid, claims } = await res.json();
return valid && claims.result === true && claims.over >= 18;
}A successful response is { "valid": true, "claims": { ... } } with the claims above. The call is server to server only: the secret key must never reach a browser, and the endpoint sends no CORS headers. The errors are listed on the HTTP API page.