Authentication
WackyTracky uses a separate SQLite database for accounts, sessions, API keys, and roles. Task data stays in your chosen task backend (todo.txt, Neo4j, or YAML files).
First administrator
On first start with an empty IAM database, the service creates:
| Username | Password |
|---|---|
|
|
Change this password before exposing the instance. The first account is placed in the Administrators group (full access).
Config
In config.yaml:
iam:
database: ./data/iam.sqlite # SQLite file for users/sessions/RBAC
auth: {} # optional httpauthshim settings (JWT, trusted headers, mTLS)
-
iam.database— Path to the IAM SQLite file. Created automatically if missing. -
auth— Optional httpauthshim configuration for JWT, reverse-proxy headers, or mTLS. Empty{}is valid (username/password only).
Persist the IAM database (and your task data) across container restarts with volumes.
Browser sessions vs API keys
| Method | How |
|---|---|
Web UI |
Login sets an HttpOnly cookie named |
Scripts / MCP (HTTP) |
Create an API key in the UI, send
|
Read-only API keys cannot change data. Cookie auth is not used on
/mcp; use a Bearer API key there.
How access works
Permissions come from groups and roles, not from ticking boxes on a single user:
-
A role lists permissions (for example
app.accessorusers.view). -
A group is given one or more roles.
-
Users belong to groups and inherit the union of those roles.
Built-in seeds include the Everyone group (member access) and Administrators (superuser). Do not leave the system with zero administrators.
Development: disable auth
For local development only:
export WACKYTRACKY_DEV_DISABLE_AUTH=true
Requests run as an anonymous superuser. Never enable this in production.
To allow non-HTTPS cookies in local HTTP:
export WACKYTRACKY_SECURE_COOKIES=false
Optional single sign-on
Extend auth: for JWT, trusted headers, or mTLS via httpauthshim. Strip
inbound identity headers at your reverse proxy unless you trust the
source. Most self-hosted setups only need username and password.
JWT from a reverse proxy (Cloudflare Access)
WackyTracky can trust a signed JWT added by an authenticating reverse proxy, such as Cloudflare Access. Users who reach WackyTracky through the proxy are signed in automatically:
auth:
jwt:
certsUrl: "https://<team>.cloudflareaccess.com/cdn-cgi/access/certs"
issuer: "https://<team>.cloudflareaccess.com"
aud: "<Access application AUD tag>"
claimUsername: "email"
header: "Cf-Access-Jwt-Assertion"
cookieName: "CF_Authorization"
-
certsUrlverifies the token signature (pubKeyPathorhmacSecretcan be used instead). Always setissuerandaud. -
claimUsernameis the claim used as the WackyTracky username. -
headerandcookieNamesay where the token is read from; set either or both.
The startup log shows httpauthshim: JWT header authentication enabled
(and … cookie …) when it is active. Only enable this when
WackyTracky is reachable solely through the proxy.
The first time a JWT user visits, their account is created automatically
(created_by: sso-autocreated) and added to the Everyone group. Grant
further groups or roles from the IAM pages. Usernames match exactly, so an
existing local account with the same username is used as-is.
Signing out and switching accounts
Signing out of a JWT session does not end the proxy’s session. Instead
WackyTracky sets a wacky-tracky-sso-off cookie in that browser and
ignores the JWT while it is present, so the login form stays and you can
sign in with a username and password.
To go back to the JWT user, choose Sign in with Single Sign-On on the login page. This clears the cookie and signs you in from the proxy again.