JWT Authentication Quick Reference

Every route under /v1 (and /api/v1) of the HeliosDB-Lite REST API requires a JSON Web Token. The server verifies tokens with the shared secret in HELIOSDB_JWT_SECRET; your application or identity service signs them with the same secret.

Quick Start

1. Start the Server with a Secret

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb

The server refuses to start when HELIOSDB_JWT_SECRET is unset or empty.

2. Sign a Token

Tokens use HS256 and must carry the issuer heliosdb-api and the audience heliosdb-client. Example with Python and PyJWT:

import os, time, uuid
import jwt  # pip install PyJWT

now = int(time.time())
token = jwt.encode(
    {
        "sub": "app_rw",                 # user (SQL role) the request runs as
        "tenant_id": "default",
        "client_id": str(uuid.uuid4()),
        "iat": now,
        "nbf": now,
        "exp": now + 3600,               # 1 hour
        "jti": str(uuid.uuid4()),
        "iss": "heliosdb-api",
        "aud": "heliosdb-client",
        "scopes": [],
    },
    os.environ["HELIOSDB_JWT_SECRET"],
    algorithm="HS256",
)

3. Call the API

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/v1/branches

Token Claims

Claim	Type	Meaning
`sub`	string	User the request is executed as
`tenant_id`	string	Tenant identifier
`client_id`	UUID	Client identifier
`exp`	Unix time	Expiry; expired tokens are rejected
`nbf`	Unix time	Not valid before
`iat`	Unix time	Issued at
`jti`	string	Unique token ID
`iss`	string	Must be `heliosdb-api`
`aud`	string	Must be `heliosdb-client`
`scopes`	string list	Permissions; `admin` lets a caller cancel other users’ queries

Requests run as the sub user, so GRANT and row-level security apply to REST calls.

Security Checklist

Use a strong random secret (32 bytes or more)
Keep the secret in a secret manager or an environment file readable only by the service
Serve the API over TLS (for example behind a reverse proxy)
Keep token lifetimes short (1 hour is a good default)
Never log tokens
Monitor authentication failures

Troubleshooting

Error	Cause	Solution
401 on every request	Token signed with a different secret	Sign with the server’s `HELIOSDB_JWT_SECRET`
401 after a while	Token expired	Issue a new token
401 with a fresh token	Wrong `iss`, `aud` or algorithm	Use HS256, `heliosdb-api`, `heliosdb-client`
Server does not start	`HELIOSDB_JWT_SECRET` unset	Export the secret before `heliosdb-lite start`

API-key authentication and a token-issuing endpoint are planned.