Skip to content

Authentication & projects

Kinglet ships with real user accounts: email + password sign-in, server-side sessions in an HttpOnly cookie, three built-in roles, and multiple projects with their own API keys.

Authentication is powered by Better Auth with the Drizzle adapter, tuned per its performance guide:

  • better-auth/minimal — Kysely is not bundled (Drizzle handles the database).
  • Session cookie cache (5 min) — getSession reads a signed cookie instead of hitting the database on every request.
  • Indexes on user.email, session.userId/token, account.userId, and verification.identifier.
  • Public self-signup is disabled; accounts are created by administrators.

When the users table is empty, Kinglet creates the administrator:

Env var Default Notes
KINGLET_ADMIN_EMAIL admin@kinglet.local login identifier
KINGLET_ADMIN_PASSWORD (generated) printed once + written to admin-password.txt

These only apply on the first boot — changing them later does nothing. The administrator cannot be deleted.

Role Can do
admin everything: projects, users, keys, logs, monitors. Cannot be deleted or demoted while last
member read/write logs, manage monitors, manage API keys
viewer read logs and monitors only

Roles map to explicit permission keys (logs.read, monitors.write, keys.write, users.read, …) internally, so custom roles later are a data change rather than a refactor.

Admins always have access to every project. Everyone else needs a project_members assignment:

  • Members get their role’s write capabilities (logs, monitors, keys) inside assigned projects.
  • Viewers get read-only access inside assigned projects.
  • Assign or remove people in /settings → projects & keys while the project is selected.
  • Upgrading from an older Kinglet backfills every user into every existing project, so nobody loses access; prune assignments afterwards.

The API exposes this as GET/POST /v1/projects/:id/members and DELETE /v1/projects/:id/members/:userId (admin only). A non-member requesting another project’s data gets a 404, so project ids cannot be probed.

Every project owns its events, monitors, alert history, and API keys. Switch projects from the header dropdown; the logs, histogram, live tail, monitors, and alerts all follow. Admins create and delete projects in /settings.

Machine credentials live per project with explicit scopes — a key never inherits a human role:

Scope Allows
ingest POST /v1/events
query GET /v1/events, /v1/histogram, /v1/services, /v1/stream

Keys look like kl_… and are shown once at creation. Revoke them any time in /settings → projects & keys; the list keeps a display prefix, scopes, creator, and last-used time. A key created without an explicit scopes array defaults to ["ingest"]; unknown scopes are rejected with a 400. When a user is demoted or deleted, keys they created are revoked.

Terminal window
curl -X POST http://localhost:8080/v1/events \
-H "Authorization: Bearer kl_…" \
-H "Content-Type: application/x-ndjson" \
--data-binary '{"level":"info","message":"hello","service":"my-app"}'

API keys are bound to their project — no ?project= needed, and they cannot list projects, manage monitors, or touch users.

  1. Authorization: Bearer kl_… → project-scoped API key
  2. Authorization: Bearer tok_… → legacy global token (KINGLET_TOKENS): all projects, full access — meant for quick tests and old automation. Set KINGLET_DISABLE_LEGACY_TOKENS=1 to turn this path off entirely.
  3. better-auth.session_token cookie → signed-in user, with role permissions

Browser routes accept the cookie; project-scoped calls use ?project=<id>. SSE accepts ?key=/?token= for shipper-style clients that cannot send headers. Sessions last KINGLET_SESSION_DAYS (default 30). Role changes and account deletion delete the user’s sessions and API keys; mutating requests always bypass the cookie cache, so a demoted user cannot keep writing.