DocsHTTP API

HTTP API reference

Planned

The browser SDK calls this API for you. Use the reference to understand what happens on the wire, to debug, or to build a client for a platform without the SDK.

Conventions

  • Base URL https://api.ageseal.eu. JSON in, JSON out, in Unicode. Request bodies are limited to 64 KiB, counted in bytes. A larger body gets 413 as soon as the limit is passed, with or without a length header.
  • Times in responses are Unix seconds unless a field says otherwise.
  • Every response carries Cache-Control: no-store. The API never sets cookies.
  • Publishable keys (pk_test_..., pk_live_...) are public and go in the page. Secret keys (sk_test_..., sk_live_...) stay on your server.
  • Calls from a browser must come from an allowed origin of the site, exactly as listed in the dashboard.

Errors

An error is an HTTP status and a body with a stable code. Codes are stable, messages are not, so branch on the code.

error.json
{ "error": { "code": "origin_not_allowed", "message": "..." } }

POST /v1/sessions

Starts a check. Called by the SDK from your page.

Body of POST /v1/sessions
FieldTypeDescription
keystring, requiredA publishable key.
over16, 18 or 21, optionalThe age to check. The threshold used is the larger of this and the minimum age set for the site in the dashboard, so a page can raise the age but never lower it.

The API checks, in order: the rate limit per IP address, the body, the rate limit per publishable key, that the key exists and is not revoked, that Origin is an allowed origin of the site, and, for a live key, that the site is live and its domain verified. A test key works whatever the site status.

request
curl -X POST https://api.ageseal.eu/v1/sessions \
  -H "Origin: https://shop.example.com" \
  -H "Content-Type: application/json" \
  -d '{ "key": "pk_test_9fK2", "over": 18 }'

Response 201

response.json
{
  "id": "ses_2c1v...",
  "expires_at": 1795000300,
  "mode": "test",
  "over": 18,
  "request": {
    "digital": {
      "requests": [
        { "protocol": "org-iso-mdoc", "data": { "deviceRequest": "<base64url>", "encryptionInfo": "<base64url>" } },
        { "protocol": "openid4vp-v1-unsigned", "data": { "response_type": "vp_token", "response_mode": "dc_api.jwt" } }
      ]
    }
  }
}

request is passed unchanged to navigator.credentials.get(request). It asks only for the age over attribute, with intent to retain set to false. A session lasts 5 minutes. The second request is shortened here.

Errors of POST /v1/sessions
StatusCodeMeaning
400invalid_requestMalformed body.
401unknown_keyNo such publishable key.
401key_revokedThe key was revoked in the dashboard.
403origin_not_allowedThe page origin is not an allowed origin of the site.
403site_not_liveA live key was used before the site went live. The SDK falls back to its preview behaviour.
429rate_limitedSlow down.

POST /v1/sessions/:id/result

Sends what the wallet returned and receives the token. Called by the SDK, from the same origin as the session.

request.json
{ "protocol": "org-iso-mdoc", "data": { "response": "<base64url>" } }

protocol and data are credential.protocol and credential.data from the browser, unchanged. For openid4vp-v1-unsigned, data is { "response": "<JWE>" }. A wallet error object such as { "error": "access_denied" } is accepted and reported as wallet_error.

Response 200

response.json
{ "result": "pass", "over": 18, "method": "mdoc", "token": "eyJ...", "expires_at": 1795000600 }

result is pass or fail. A visitor under the threshold gets a normal 200 with fail and a token whose result claim is false. The first call consumes the session, successful or not. A failed verification needs a new session.

The key and the site are checked again. If the key was revoked while the session was open, or a live site was switched back to test or lost its domain verification, the result is refused and the session is consumed.

Errors of POST /v1/sessions/:id/result
StatusCodeMeaning
400invalid_requestMalformed body or session id.
401key_revokedThe key that started the session was revoked since.
403origin_not_allowedOrigin is not the origin of the session.
403site_not_liveA live session, and the site is no longer live or verified.
404session_not_foundUnknown id.
409session_usedThe session was already consumed (replay).
410session_expiredOlder than 5 minutes.
422unsupported_formatThe protocol, credential format or device authentication is not supported.
422wallet_errorThe wallet returned an error, or the visitor cancelled.
422decryption_failedThe response is not encrypted to this session.
422invalid_responseNot a well formed response, wrong document count or document type.
422untrusted_issuerThe certificate chain does not end at a trusted root for this key mode.
422issuer_signature_invalidThe issuer signature or a certificate signature failed.
422mso_not_valid_yet, mso_expiredThe credential is outside its validity window. 60 seconds of skew are allowed.
422digest_mismatchThe disclosed element does not match the signed digest.
422device_auth_failedThe device signature does not verify for this nonce and origin.
422claim_missingThe requested age over attribute was not disclosed.
422unexpected_elementsAnything other than the one requested element was disclosed. The response is rejected and the data is dropped unread.
429rate_limitedSlow down.

POST /v1/sessions/:id/abandon

Counts a session that did not produce a result. Called by the SDK, from the same origin as the session. Abandoned attempts are never billed, and sessions of test keys are not counted at all.

request.json
{ "reason": "abandoned" }

reason is abandoned (the default: the visitor cancelled or no wallet answered) or fallback (the site sent the visitor to its fallback URL). The response is 200 { "ok": true }. A session that already has a result returns 409 session_used, and an expired session returns 410 session_expired. No other data is accepted or stored.

POST /v1/tokens/redeem

Optional single use check, from your server. Authorization is the secret key of the site.

request
curl -X POST https://api.ageseal.eu/v1/tokens/redeem \
  -H "Authorization: Bearer sk_test_Hn4x" \
  -H "Content-Type: application/json" \
  -d '{ "token": "eyJ..." }'

Response 200

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

The signature, exp, mode (must match the key mode), iss and aud are checked, then the jti is stored until exp. A live secret key accepts iss https://api.ageseal.eu with your site id as aud. A test secret key accepts iss https://api.ageseal.eu/test with test: and your site id as aud. The call is rate limited per IP address and per secret key. No CORS headers are sent: call it from a server only.

Errors of POST /v1/tokens/redeem
StatusCodeMeaning
400invalid_requestMalformed body.
401unknown_keyNo such secret key.
401key_revokedThe key was revoked.
409token_already_redeemedThis token was redeemed before.
422token_invalidBad signature, expired, wrong site, or a token of the other mode (a test token with a live key, or the other way round).
429rate_limitedSlow down.

GET /.well-known/jwks.json

Public. Returns the P-256 public keys that verify result tokens, at https://api.ageseal.eu/.well-known/jwks.json. The response allows any origin and is cached for 5 minutes. See Verify tokens.

Not done yet

These parts of the verification are not built. They decide how many visitors can pass at launch, so read them before you plan around the API.

  • Production trust roots. The live trust list is empty, so no live key can pass verification yet. The list of EU age verification issuers still has to be loaded, signature checked and refreshed.
  • Signed requests. Requests are not signed. The EU age verification app does not need it, but Apple Wallet requires a signed reader request, and EUDI Wallets are expected to require a registered access certificate from the end of 2026.
  • SD-JWT credentials and zero knowledge proofs. Not supported. Plain mdoc is.
  • Revocation checking. Certificate chains are checked for signature, validity, names, key usage, the document signer profile and critical extensions, but not against revocation lists.
  • Real wallet testing. The flow is tested against generated fixtures, not against a real age verification app, Apple Wallet or Google Wallet.
  • Local development. Allowed origins must be https without a port, so http://localhost does not work with a test key.