Authentication

Two ways, both accepted by the same middleware:

Session cookie (browser)

POST /api/v1/auth/login with { "email": "...", "password": "..." } sets a cookie named illusiondb_session, valid for 7 days. POST /api/v1/auth/logout deletes it server-side.

API token (scripts, external clients)

Create a token under Settings → My account: POST /api/v1/auth/tokens with { "name": "..." } – the response contains the raw token value exactly once. Send it afterward as:

Authorization: Bearer <your-token>

The token itself is a plain random value (base64url-encoded) – no fixed prefix. Revoke a token via DELETE /api/v1/auth/tokens/{id}.

Alternatively, for cases without control over your own headers (e.g. an <img src="..."> pointing at a file attachment, a directly linked CSV export): the same token as a query parameter ?token=... (or &token=... if a query string already exists):

GET /api/v1/tables/{tableId}/records/{pk}/attachments/{columnId}/{fileId}?token=<your-token>

If an Authorization header is also set, the header wins. Security note: a token in the URL can potentially end up in server/proxy logs, browser history, and Referer headers of downstream requests – use the Authorization header wherever possible, and reserve the query variant specifically for cases like embedded images or direct links.

Public endpoints

Reachable with no login at all: POST /auth/login, GET /auth/setup-status, POST /auth/setup (initial setup), GET /healthz, GET /version. The document generator endpoints and custom endpoints marked public (see Custom endpoints) also run outside the normal middleware – these decide for themselves, per call, whether a login is required.