Authentication

The system has two authentication layers: admin session auth for the web UI, and API key auth for programmatic access.

API keys

API keys are required for any programmatic call to the REST API or MCP server. The public FAQ endpoint and the embedded chat UI are the only surfaces that do not require a key.

Keys are prefixed cape_ followed by 64 hex characters. Example:

cape_a3f1c9d2e847b6a0f21d3c9e7b4a5f8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6

Creating a key

  1. Go to API Keys in the admin sidebar
  2. Enter a label (e.g. Production, CI/CD pipeline, Cursor integration)
  3. Optionally set rate limits — rpm (requests per minute) and rpd (requests per day). Leave blank for no limit.
  4. Click Create — copy the key immediately. It is shown only once.

How keys are stored

Only a SHA-256 hash of the key is stored in the database. The plaintext is never persisted. If a key is lost, revoke it and create a new one.

Using a key

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer cape_a3f1c9...

This applies to all REST API endpoints that require auth, as well as the MCP server.

Rate limiting

If rate limits are configured, the system enforces them per key:

  • rpm — requests per minute, sliding window
  • rpd — requests per day, rolling 24 hours

Exceeding a limit returns 429 Too Many Requests.

Revoking a key

Click Revoke next to a key in the admin panel. Revocation is immediate and permanent. Revoked keys remain visible for audit purposes but cannot be re-activated. Each key also shows total request count and last-used date.

Admin authentication

The admin UI uses email/password login via NextAuth. Sessions are JWT-based. Admin accounts are created through the seed script — there is no self-registration.

Seeding an admin user

ADMIN_INITIAL_EMAIL=you@example.com \
ADMIN_INITIAL_PASSWORD=yourpassword \
npx tsx scripts/seed-admin.ts

This is idempotent — running it again when the user already exists is a no-op.

Admin API access

Admin-only endpoints (API key management, conversations, ingest jobs) accept either:

  • A valid NextAuth session cookie (from the web UI)
  • A valid API key in the Authorization header

This lets CI/CD pipelines call admin endpoints without a browser session.