# verify-token

Verifies the **API token** that the request is sent with.

- **Route:** `POST /api/v2/system/verify-token`
- **Category:** `system`
- **Authentication:** required, with the API token, which is what the route verifies
- **Answer:** a single JSON envelope

The route **does nothing but check the token**, so a client or a tool can find out whether its token is valid **without touching the data**, for example right after it connects. A valid token is answered with `200`, a **missing or wrong one with `401`**, as on every route that requires one. EventSourcingDB has a **single API token** that grants access to everything, see **[Security and Access Control](/docs/eventsourcingdb/security-and-access-control)**.

## Request

The route takes **no body**, and ignores one that is sent. The token goes into the `Authorization` header, with the `Bearer` scheme:

```shell
curl \
  -X POST \
  -H "authorization: Bearer secret" \
  http://localhost:3000/api/v2/system/verify-token
```

## Answer

The answer is a **single envelope** of the type `event`, which holds a **[CloudEvent](/docs/eventsourcingdb/cloud-events)** of the type `io.eventsourcingdb.api.token-verified`. Its `data` is an **empty object**, since the type of the event says everything.

For a valid token, the request above is answered with:

```json
{
  "type": "event",
  "data": {
    "specversion": "1.0",
    "id": "01a180c6-ea94-7b5a-83c3-acd5e4662506",
    "source": "https://www.eventsourcingdb.io",
    "type": "io.eventsourcingdb.api.token-verified",
    "subject": "/api/v2/system/verify-token",
    "time": "2026-10-28T04:31:22.260741Z",
    "datacontenttype": "application/json",
    "data": {}
  }
}
```

## Status Codes

The server answers with a status code other than `200` where it cannot take the request at all, as described in **[Errors](/docs/eventsourcingdb/api#errors)**:

- **`401`**: The API token is missing or wrong, which is the answer that tells you the token is not valid. It carries the header `WWW-Authenticate: Bearer`.
- **`429`**: Too many requests were sent; the answer says when to try again.
- **`500`**: The server failed unexpectedly.
- **`503`**: The server is shutting down.