---
title: "HTTP/REST API Configuration"
---

# HTTP/REST API Configuration

The HTTP gateway is configured with `heliosdb-full` startup flags and environment
variables. The config file has no HTTP section (the server reads only `[storage]` keys
from it). Run `heliosdb-full --help` to see every flag with its environment variable.

## Port and bind address

| Setting | Flag | Environment variable | Default |
|---------|------|----------------------|---------|
| Port | `--http-port <port>` | `HELIOSDB_HTTP_PORT` | 8443 |
| Turn the gateway off | `--no-http` | — | on |
| Bind address (all listeners) | `--bind-addr <addr>` | `HELIOSDB_BIND_ADDR` | `127.0.0.1` |
| Allow a non-loopback bind | `--allow-external` | `HELIOSDB_ALLOW_EXTERNAL` | off |

```bash
# Default: http://127.0.0.1:8443
heliosdb-full --data-dir /var/lib/heliosdb

# Another port, reachable from a private network
heliosdb-full --data-dir /var/lib/heliosdb --http-port 9443 \
  --bind-addr 10.0.0.12 --allow-external
```

`--bind-addr` applies to every listener. The server refuses to start on a
non-loopback address without `--allow-external` (accepted values `1/0`, `true/false`,
`yes/no`, `on/off`).

In a container the image binds `0.0.0.0` and sets `HELIOSDB_ALLOW_EXTERNAL=true`;
publish the port you use, for example `-p 127.0.0.1:8443:8443`, or
`-e HELIOSDB_HTTP_PORT=9443 -p 127.0.0.1:9443:9443`.

## TLS

:::caution[TLS: next release]
HeliosDB Full listeners do not terminate TLS; put a TLS-terminating proxy in
front, and native PostgreSQL TLS (with post-quantum key exchange preferred) is
planned for the next release. The `--tls-cert`, `--tls-key` and `--tls-require`
flags in this section belong to that release.
:::

The gateway serves plain HTTP; the TLS flags (`--tls-cert`, `--tls-key`,
`--tls-require`) apply to the PostgreSQL listener only. For HTTPS, terminate TLS in
front of the gateway:

```nginx
server {
    listen 443 ssl;
    server_name db-api.example.internal;
    ssl_certificate     /etc/nginx/tls/db-api.crt;
    ssl_certificate_key /etc/nginx/tls/db-api.key;

    location / {
        proxy_pass http://127.0.0.1:8443;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

## Authentication

| Setting | How | Default |
|---------|-----|---------|
| API key | `HELIOSDB_API_KEY` environment variable | unset: every non-public route returns 401 |
| Development without a key | `--auth-mode trust` (`HELIOSDB_AUTH_MODE`) | `scram`; `trust` is accepted on a loopback bind only |

Clients send `Authorization: Bearer <key>` or `X-API-Key: <key>`. `GET /`, `/health`,
`/healthz`, `/ready`, `/readyz`, `/status` and `/api/v1/status` need no key. The key
is shared (not per user); treat it like a superuser password and load it from a
secrets manager or a root-only environment file, never the command line.

## Sessions, pool and limits

| Setting | Flag (environment variable) | Default |
|---------|-----------------------------|---------|
| Pinned sessions for transactions | `--http-sessions` | off (session routes return 501) |
| Handler pool for `/api/v1/query` | `--http-pg-pool-size` (`HELIOSDB_HTTP_PG_POOL_SIZE`) | 16 |
| New connections per client IP | `--conn-rate-limit` (`HELIOSDB_CONN_RATE_LIMIT`) | 500 per minute |
| Queries per client IP | `--query-rate-limit` (`HELIOSDB_QUERY_RATE_LIMIT`) | not limited |
| Connection and query limiters | `HELIOSDB_RATE_LIMITING=false` turns them off | on |
| Concurrent connections, all listeners | `--max-connections` (`HELIOSDB_MAX_CONNECTIONS`) | 10000 |

The session flags (`--http-max-sessions`, idle and lifetime timeouts, concurrency
mode, IP binding, `--node-id`) and the AI provider variables are listed in the
[HTTP/REST API reference](/docs/full/reference/api/http_rest_api/).

## systemd example

```ini
# /etc/systemd/system/heliosdb.service (excerpt)
[Service]
EnvironmentFile=/etc/heliosdb/heliosdb.env   # HELIOSDB_API_KEY, HELIOSDB_SUPERUSER_PASSWORD; mode 0600
ExecStart=/usr/local/bin/heliosdb-full --data-dir /var/lib/heliosdb \
  --http-port 8443 --bind-addr 10.0.0.12 --allow-external
```