# HTTP API reference · Ageseal docs

Canonical URL: https://ageseal.eu/docs/api

> Endpoints, requests, responses and error codes of the Ageseal verification API version 1.

Status: 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.

> **Planned: Draft reference.** The API is built but not deployed. It is planned at https://api.ageseal.eu. Everything here may change before the first release. The live trust list is still empty, so live keys cannot pass verification yet, and no real wallet has been tested against it.

## 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`:

```json
{ "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.

`request`:

```sh
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`:

```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.

| 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.

`request.json`:

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

```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.

| 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.

`request.json`:

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

```sh
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`:

```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.

| 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](https://ageseal.eu/docs/verify#public-keys).

## 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.

Docs: [Overview](https://ageseal.eu/docs), [Quickstart](https://ageseal.eu/docs/quickstart), [Browser SDK](https://ageseal.eu/docs/sdk), [Verify tokens](https://ageseal.eu/docs/verify), [HTTP API](https://ageseal.eu/docs/api), [Fallback](https://ageseal.eu/docs/fallback), [Testing and going live](https://ageseal.eu/docs/testing), [Privacy and security](https://ageseal.eu/docs/privacy-security).
