DocsHTTP API
HTTP API reference
PlannedThe 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": { "code": "origin_not_allowed", "message": "..." } }POST /v1/sessions
Starts a check. Called by the SDK from your page.
| Field | Type | Description |
|---|---|---|
key | string, required | A publishable key. |
over | 16, 18 or 21, optional | The 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.
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
{
"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.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed body. |
| 401 | unknown_key | No such publishable key. |
| 401 | key_revoked | The key was revoked in the dashboard. |
| 403 | origin_not_allowed | The page origin is not an allowed origin of the site. |
| 403 | site_not_live | A live key was used before the site went live. The SDK falls back to its preview behaviour. |
| 429 | rate_limited | Slow 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.
{ "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
{ "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.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed body or session id. |
| 401 | key_revoked | The key that started the session was revoked since. |
| 403 | origin_not_allowed | Origin is not the origin of the session. |
| 403 | site_not_live | A live session, and the site is no longer live or verified. |
| 404 | session_not_found | Unknown id. |
| 409 | session_used | The session was already consumed (replay). |
| 410 | session_expired | Older than 5 minutes. |
| 422 | unsupported_format | The protocol, credential format or device authentication is not supported. |
| 422 | wallet_error | The wallet returned an error, or the visitor cancelled. |
| 422 | decryption_failed | The response is not encrypted to this session. |
| 422 | invalid_response | Not a well formed response, wrong document count or document type. |
| 422 | untrusted_issuer | The certificate chain does not end at a trusted root for this key mode. |
| 422 | issuer_signature_invalid | The issuer signature or a certificate signature failed. |
| 422 | mso_not_valid_yet, mso_expired | The credential is outside its validity window. 60 seconds of skew are allowed. |
| 422 | digest_mismatch | The disclosed element does not match the signed digest. |
| 422 | device_auth_failed | The device signature does not verify for this nonce and origin. |
| 422 | claim_missing | The requested age over attribute was not disclosed. |
| 422 | unexpected_elements | Anything other than the one requested element was disclosed. The response is rejected and the data is dropped unread. |
| 429 | rate_limited | Slow 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.
{ "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.
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
{
"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.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed body. |
| 401 | unknown_key | No such secret key. |
| 401 | key_revoked | The key was revoked. |
| 409 | token_already_redeemed | This token was redeemed before. |
| 422 | token_invalid | Bad signature, expired, wrong site, or a token of the other mode (a test token with a live key, or the other way round). |
| 429 | rate_limited | Slow 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://localhostdoes not work with a test key.