verify-token

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

Request#

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

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

{
  "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:

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