Skip to content

Security and Access Control

This guide explains how access to EventSourcingDB is secured and what best practices apply when deploying it in production. It covers token-based access, network isolation, and future plans for fine-grained authorization.

Overview

Access to EventSourcingDB is controlled via a single API token. This applies to both the API and the management UI. If a request includes a valid token, it is accepted. If not, it is rejected. There are no user accounts, roles, or permissions — access is all-or-nothing.

The database is designed to run in private, secured networks and should not be exposed to the public internet.

Access Control with API Token

All HTTP endpoints are protected using a single shared token:

  • The same token is required for both the HTTP API and the management UI
  • Requests without a valid token are rejected with the HTTP status code 401 Unauthorized
  • The token must be passed in the Authorization header using the Bearer scheme

Example:

Authorization: Bearer <API_TOKEN>

There are no username/password combinations or user accounts. Anyone who knows the token has full access.

Token Recommendation

Although there are no formal constraints, we recommend choosing a token of at least 32 characters that includes uppercase and lowercase letters and digits. Avoid using guessable or common strings.

Verifying API Tokens

To check whether an API token is valid, send a POST request to /api/v1/verify-api-token and include the token in the Authorization header using the Bearer scheme:

curl -i \
  -X POST \
  -H "Authorization: Bearer <API_TOKEN>" \
  http://localhost:3000/api/v1/verify-api-token

If the token is valid, the server responds with HTTP status code 200 OK and the following response:

{
  "specversion": "1.0",
  "id": "0",
  "time": "...",
  "source": "https://www.eventsourcingdb.io",
  "subject": "/api/v1/verify-api-token",
  "type": "io.eventsourcingdb.api.api-token-verified",
  "datacontenttype": "application/json",
  "data": {}
}

If the token is missing or invalid, the server responds with HTTP status code 401 Unauthorized.

This endpoint is useful for systems or tools that need to explicitly verify the validity of an API token without invoking any other functionality.

Network Isolation

As with other infrastructure components such as databases or message queues, access to EventSourcingDB should be strictly limited to internal systems. It should not be exposed on the public internet.

Recommended approaches include:

  • Running EventSourcingDB in a private subnet or internal-only cluster
  • Using firewall rules, security groups, or network policies to limit access
  • Placing EventSourcingDB behind a reverse proxy or API gateway, if needed

Do Not Expose Publicly

Never expose EventSourcingDB directly to the internet. It is intended for use inside trusted environments and internal networks only.

The same applies to the management UI — it should be reachable only from internal systems or secured jump hosts.

Best Practices

  • Keep the API token secret and secure
  • Rotate the token periodically
  • Avoid passing the token in URLs or query strings
  • Do not log requests that contain tokens
  • Restrict access at the network level
  • Limit UI access to trusted users or internal tools

A strong network perimeter and careful token handling are the foundation of a secure EventSourcingDB deployment.