# Security Considerations This guide outlines the security-related aspects of running EventSourcingDB in production. It covers **authentication**, **network isolation**, **secure deployment practices**, and how the system fits into a secure infrastructure. The goal is to provide a clear understanding of what EventSourcingDB does – and does not – enforce, and what responsibilities fall to the application or operations team. EventSourcingDB is designed to operate in **internal, trusted environments**. It assumes that **infrastructure-level protections** are in place and focuses on providing **secure defaults** for core interactions without introducing unnecessary complexity. There are **no user accounts**, **no built-in encryption**, and **no roles or permissions**. Instead, the system relies on simple and well-understood security measures, including **token-based access** and **strict network boundaries**. ## API Token and Access Control All access to EventSourcingDB – including the HTTP API and the management UI – is gated by a **single API token**. This token must be passed in the `Authorization` header using the `Bearer` scheme. Any request for your data that lacks a valid token is rejected with a `401 Unauthorized` response; only the few routes that check liveness or describe the API answer without it, as listed under **[Logging, Monitoring, and Surface Area](#logging-monitoring-and-surface-area)**. There is **no concept of users, sessions, or roles**. Anyone who knows the token has **full access to all functionality**. This **all-or-nothing model** is intentional. It eliminates ambiguity and simplifies both deployment and auditing. While more granular access control may be introduced in the future, the current model ensures that **authentication is deterministic** and **easily enforced at the network level**. *(Removed in 1.3; Broken in 1.2, fixed in 1.3)* Full access includes **reading files of the server**: an event schema may refer to a file on the server with a `$ref` of the form `file:///…`, which the server then reads when it registers the schema, and its error messages show the paths of the server. Give the token only to those you would let read the files that the server can read. *(Changed in 1.3)* When generating an API token, **choose a strong random value**. A minimum length of **32 characters** with a mix of **uppercase, lowercase, and digits** is recommended. Avoid predictable values or shared secrets across environments. **Tokens should never be transmitted in URLs or logged by clients or reverse proxies**. ## Network Isolation and Secure Deployment EventSourcingDB is **not designed to be exposed to the public internet**. It should be deployed **behind firewalls**, **within private subnets**, or in otherwise **secured environments** where only **trusted systems** have network access. This includes both production environments and staging setups where real data may be present. Recommended deployment options include placing EventSourcingDB behind a **reverse proxy**, **API gateway**, or **ingress controller** that handles **TLS termination**, **request validation**, or **additional authentication**. The database should only be accessible to **internal services and automation tools** that are authorized to read or write events. When deploying with Docker, **ensure that HTTP is not enabled**. The system supports **HTTPS by default**, and **TLS certificates must be provided explicitly via configuration**. The recommended production setup includes **mounting a persistent data directory**, **supplying certificate and key files**, and **disabling HTTP even if it is not enabled by default**. This prevents accidental misconfiguration and ensures that **all communication is encrypted in transit**. ## Logging, Monitoring, and Surface Area All log output from EventSourcingDB is written to **standard output in JSON format**. This output can be collected and aggregated using standard log forwarding pipelines. The system logs startup information, warnings, errors, and fatal conditions but **does not log incoming requests or sensitive values like API tokens**. This **reduces the risk of accidental data leakage** and **supports compliance with common operational policies**. *(Changed in 1.3)* Monitoring endpoints include `/api/v1/ping` and `/api/v1/health`. The former is **unauthenticated and suitable for basic liveness checks**. The latter **requires a valid API token** and returns health status metadata. Besides ping, the **OpenAPI definition** at `/.well-known/openapi` answers without a token as well; it describes the API, not your data. While these endpoints are read-only, they **may expose internal state or configuration details** and should therefore be **protected by the same network isolation as the rest of the system**. The **management UI is optional and disabled by default**. If enabled, it exposes a **visual interface for exploring stored data and monitoring system health**. It is subject to the **same token-based access as the API** and **should not be exposed outside of trusted environments**. If other observability tooling is already in use, the UI may be unnecessary and can be omitted from production deployments. *(Removed in 1.3)* If you enable **EventAI** in the management UI with `--ai-model` and `--ai-option`, EventSourcingDB sends your **event schemas**, your **prompts**, and the queries of the conversation to **OpenAI**, an external service, to generate EventQL queries; the events themselves are not sent. See **[Using EventAI](/docs/eventsourcingdb/v1.2/management-ui#using-eventai)**. ## Secure by Simplicity EventSourcingDB follows a principle of **minimalism in its security design**. Instead of introducing **partial role models**, **complex authorization rules**, or **plugin-based policies**, it keeps the **surface area small** and **behavior predictable**. It does not make assumptions about the user's infrastructure and relies on no **external services** or **external databases** that might obscure behavior or introduce hidden risks. What the system does guarantee is clear: **all access to your data is authenticated with a single token**, **all data is immutable and ordered**, and **no internal state becomes visible unless explicitly requested**. There are **no message queues** and **no hidden data flows** that could compromise data integrity or observability. What EventSourcingDB does **in the background** concerns only its own data, such as **watching the free disk space** so that it stops accepting writes when the disk runs low. The result is a system that is **easy to reason about** and **straightforward to secure**. With **proper deployment practices** – especially **network isolation** and **careful token handling** – EventSourcingDB offers a **strong foundation for secure and compliant event storage**, suitable for both development and production environments. For how to configure the API token and restrict network access, see **[Security and Access Control](/docs/eventsourcingdb/v1.2/security-and-access-control)**.