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

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

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

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

For the principles behind these measures – what EventSourcingDB enforces and what remains the responsibility of your infrastructure – see **[Security Considerations](/docs/eventsourcingdb/v1.0/security-considerations)**.