DocsVerify tokens

Verify tokens on your server

Planned

The 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:

payload.json
{
  "iss": "https://api.ageseal.eu",
  "aud": "site_7Kq2",
  "over": 18,
  "result": true,
  "method": "mdoc",
  "mode": "live",
  "iat": 1795000000,
  "exp": 1795000600,
  "jti": "Kq1v0nS3m9rXb2Z4pYw8dA"
}

Claims

Claims of the result token
ClaimValueWhat to do
isshttps://api.ageseal.eu for live, https://api.ageseal.eu/test for testMust match the live value exactly in production.
audYour site id, as shown in the dashboard. Test tokens have test: before itMust equal your site id. This stops a token made for another site, or a test token, from working on yours.
over16, 18 or 21Must be at least the age you require.
resulttrue or falseMust be true. A visitor under the threshold gets a valid token with false.
methodmdocFor your records. sd-jwt is reserved and not implemented.
modetest or liveMust be live in production. A test token already fails the iss and aud checks, but check mode as well.
iat, expUnix seconds. exp is 10 minutes after iatReject expired tokens. Allow a little clock skew, for example 30 seconds.
jtiA random token idNever 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

  1. Read the kid from the token header and pick that key from the public key set.
  2. Check the ES256 signature. Accept only ES256, never the algorithm the token asks for.
  3. Check iss, aud and exp against the live values.
  4. Check result is true, over is high enough, and mode is live in production.
  5. 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");
}

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 iss and aud the way the examples above do refuses every test token, even if it forgets to check mode.
  • 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.js
// 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 kid you 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..." }'

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.