Authentication

The API has two authentication mechanisms. They are mutually exclusive on a given request.

Account provisioning (no signup)

There is no public signup endpoint. The only ways to create a user are:

npm run user:create -- --username alice --password '…'

…or npm run db:seed for the demo superadmin / demo1234 user (intended for local exploration only).

The "superadmin" is just a regular user — the model has no role flag. Each user only sees the projects they own, so in practice you only provision as many users as people who need to manage projects from the UI. Other teams consume the API with project keys; they do not need an account.

Cookie sessions (admin UI)

POST /api/auth/login accepts { username, password } and sets a signed HTTP-only cookie. The cookie is required for every endpoint under /api/projects, /api/api-keys and project creation when called from a browser. AUTH_SECRET (env var) signs the cookie. Change it before deploying.

curl -X POST https://your-host/api/auth/login \
  -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username":"superadmin","password":"…"}'

curl https://your-host/api/auth/me -b cookies.txt

POST /api/auth/logout clears the cookie.

Project API keys (server-to-server)

For backends that need to script surveys, templates or responses, generate an API key from the admin UI under Project → API keys. Keys are project-scoped: they cannot read or modify other projects, and they cannot create projects or new API keys (those operations require a cookie session).

The key is shown once at creation time in the form svc_<random>. The server only stores a SHA-256 hash, so if you lose the key you have to revoke and re-issue.

Send it as a Bearer token in the Authorization header:

curl https://your-host/api/projects/$PROJECT_ID/surveys \
  -H "Authorization: Bearer $PROJECT_API_KEY"

API keys can be revoked at any time from the admin UI. A revoked key returns 401 on every subsequent request.

Public endpoints

Public endpoints — GET /r/{token}, GET /api/public/templates/{token} and POST/PATCH /api/public/templates/{token}/respond — require no authentication beyond knowledge of the token. Treat the token as a capability: anyone who has it can read the survey definition and submit answers.

For that reason:

• Templates are single-use (a token cannot answer multiple surveys).
• Tokens are UUIDv4, so they are not enumerable in practice.
• The metadata you attach is sent back in the public response payload, so do not put secrets in metadata.