Authentication

Every request is authenticated as either:

• An admin account via a session cookie (used by the admin UI and browser-based flows), or
• An API key (bigrag_sk_…) minted by an admin (used by backend services, SDKs, and automation).

First-run setup

A fresh install has no users. The first admin is created via the one-time setup endpoint, which is the only admin-capable endpoint that works without authentication.

# Check whether setup is still required
curl http://localhost:4000/v1/auth/setup-status
# → {"needs_setup": true}

# Create the first admin (works exactly once)
curl -X POST http://localhost:4000/v1/auth/setup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "a-strong-password",
    "display_name": "Admin"
  }'

Once at least one admin exists, setup-status returns {"needs_setup": false} and /v1/auth/setup returns 409.

The admin UI exposes the same flow at http://localhost:3000/setup. After the first admin is created, the UI redirects the signed-in admin to /onboarding to create a verified embedding preset and save Turbopuffer settings before collection work. The setup endpoint itself still only creates the first admin and session.

Session auth (admin UI, browser)

Logging in returns a bigrag_session cookie (configurable via BIGRAG_SESSION_COOKIE_NAME). All subsequent requests from that browser are authenticated by the cookie.

curl -X POST http://localhost:4000/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email": "admin@example.com", "password": "a-strong-password"}'

curl http://localhost:4000/v1/auth/me -b cookies.txt

Session cookie attributes are seeded from BIGRAG_SESSION_COOKIE_* bootstrap values and can also be managed through /v1/admin/settings. The admin UI does not expose those fields on the Security tab. In production you must set session_cookie_secure=true before serving admin traffic over HTTPS.

API key auth (SDKs, services)

API keys are minted by an admin at /v1/admin/api-keys (or via the admin UI → API keys). The plaintext key is shown once:

curl -X POST http://localhost:4000/v1/admin/api-keys \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"name": "ingestion-worker", "scopes": ["collection:read", "document:*"]}'
# → {"id": "...", "name": "ingestion-worker", "prefix": "bigrag_sk_abcd", ...,
#     "key": "bigrag_sk_abcd…_XXXXXXXXXXXXXXXXXXXXXXXX"}

Send the key as a bearer token:

curl http://localhost:4000/v1/collections \
  -H "Authorization: Bearer bigrag_sk_…"

Key fields

Collection pins and scopes are independent: a key with collection: "docs" and omitted / empty scopes has full access inside docs, while cross-collection requests stay blocked by the pin.

Scopes

Scopes use resource:action with * as a wildcard.

A key missing a required scope returns 403 with {"detail": "API key missing required scope: <scope>"}.

If a key is pinned to a single collection, that pin is enforced even on the global read helpers like /v1/documents/{id} by resolving the document's owning collection before returning it. Cross-collection status endpoints (/v1/status/overview, /v1/status/collections, and /v1/status/usage) are blocked for pinned keys.

Which endpoints accept which auth

* Read-only auth endpoints (/me) accept either; state-changing ones (/password, /logout-all) require a session.

Password policy

• Argon2id hashed at rest
• Minimum 8 characters (enforced on /setup, user create, and password change)
• Changing a password revokes every existing session for that user

Error responses