Authentication and API keys
The engine's four auth modes, which one to use where, and how to mint and use an API key.
LOAMS_AUTH_MODE picks how the engine authenticates the native port, Qdrant, Elasticsearch and Flight SQL. /health and /ready stay public in every mode.
| Mode | Who it accepts | Use it for |
|---|---|---|
off | Loopback clients only; every other client is refused | loams dev on your own machine. The default for loams dev |
tailscale | The Tailscale identity that tailscale serve adds, trusted only on LOAMS_TAILSCALE_LISTEN (127.0.0.1:7781) and narrowed by LOAMS_TAILSCALE_ALLOWED_USERS | People using the hosted console from a tailnet device. The compose stack's default |
apikey | Authorization: Bearer lk_…, checked against hashes in LOAMS_API_KEYS_FILE | The CLI, SDKs, scripts, CI and servers |
oidc | Bearer JWTs from LOAMS_OIDC_ISSUER (RS256 or EdDSA), verified against its JWKS | Signing in with a Loams account or your own identity provider |
Modes combine as a comma list, such as tailscale,apikey: people reach the console through Tailscale, and machines use keys.
Mint an API key
loams auth new-key --label ci --append ./api-keysThe command prints the key once on stdout and appends only its hash to the file (created with mode 0600); without --append it prints the line for you to add yourself. The key is never stored in plain text, so copy it now. Then start the engine with the file:
LOAMS_AUTH_MODE=apikey LOAMS_API_KEYS_FILE=./api-keys loams devIn the compose stack, the engine reads secrets/api-keys (next to compose.yaml) as /etc/loams/secrets/api-keys. From deploy/release:
loams auth new-key --label ci --append secrets/api-keys
# in .env: LOAMS_AUTH_MODE=tailscale,apikey
docker compose up -d loamsUse the key
curl -s https://loams.<tailnet>.ts.net/v1/namespaces/demo/sql \
-H "Authorization: Bearer $LOAMS_API_KEY" -H 'content-type: application/json' \
-d '{"query": "SELECT _id, body FROM kb LIMIT 3"}'Every SDK reads it from an option or from LOAMS_API_KEY (apiKey(...) in TypeScript, api_key= in Python, loams.APIKey(...) in Go, EnvTokenSource in C#). See SDKs.
Machines on a tailnet need keys
Tailscale's identity headers are empty for requests from tagged devices (Tailscale Serve). A CI runner or server that joined your tailnet with a tagged auth key therefore cannot use tailscale mode: give it an API key, and add apikey to the mode list.
OIDC
oidc needs LOAMS_OIDC_ISSUER (https://auth.loams.dev or your own issuer), LOAMS_OIDC_AUDIENCE=loams-console, and one of LOAMS_OIDC_ALLOWED_EMAILS, LOAMS_OIDC_ALLOWED_SUBJECTS or LOAMS_OIDC_ALLOWED_GROUPS: the engine refuses to start without one. The engine fetches the issuer's JWKS outbound and caches it; the auth service never connects to your stack.
What is not hardened yet
Authorization is coarse in 0.1.0: a valid token or key can do anything the engine can do. Per-namespace roles and tenant quotas are Planned. Keep keys out of source control and rotate them by removing their line from the key file and restarting the engine.