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) —getSessionreads a signed cookie instead of hitting the database on every request. - Indexes on
user.email,session.userId/token,account.userId, andverification.identifier. - Public self-signup is disabled; accounts are created by administrators.
First boot
Section titled “First boot”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.
Project membership
Section titled “Project membership”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.
Projects
Section titled “Projects”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.
API keys
Section titled “API keys”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.
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.
How auth is resolved
Section titled “How auth is resolved”Authorization: Bearer kl_…→ project-scoped API keyAuthorization: Bearer tok_…→ legacy global token (KINGLET_TOKENS): all projects, full access — meant for quick tests and old automation. SetKINGLET_DISABLE_LEGACY_TOKENS=1to turn this path off entirely.better-auth.session_tokencookie → 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.