Skip to content

Authentication

The single-owner auth model, credentials, session tokens, and API keys.

Authentication is off until the built-in admin user has a password (SUMIDOKU_AUTH_PASSWORD, or the legacy SUMIDOKU_BASIC_PASSWORD alias). With a password configured, the web UI shows a login page and /api/v1 requires a session credential. Browser requests use the login cookie; CLI and other non-browser clients may use Authorization: Bearer <token> (a login-issued session token or UI-managed API key). Unauthenticated requests get a uniform 401 ({"error":{"code":"unauthorized"}}).

With auth off, every request acts as the built-in admin — a no-password deployment behaves exactly like a single-user one.

One owner

The built-in admin (USER_ID = 1) is the only identity. There are no additional accounts, roles, user-management routes or Users page. Library, progress, categories, sources, downloads, updates, sync, backups and all settings belong to this owner. Authenticated requests act as admin; the API does not expose a role field.

Login uses the admin’s username and password. Existing admin sessions stay valid across the single-owner migration. Other accounts and their sessions are removed.

Existing non-admin data

Migration 0019 removes all non-admin accounts and their libraries, progress, categories, settings, downloads and sync state. There is no export, merge or restore path for those accounts. Built-in admin data is preserved, including legacy rows whose user_id is 1; these legacy storage details do not represent a multi-user product model.

The release notes for this change explicitly call out the deletion as a breaking change.

Credentials

  • Admin username — SUMIDOKU_AUTH_USERNAME env or auth.username in config.toml; unset or blank means admin. On every boot a configured value is written onto the built-in admin’s user row. GET /api/v1/auth/status returns it as the top-level username field only with a valid authenticated identity; anonymous responses omit it, and the login page starts with an empty username field.

  • Admin password — SUMIDOKU_AUTH_PASSWORD env or auth.password in config.toml. On every boot it is hashed (argon2) onto the built-in admin’s user row, so the config value overrides a password previously changed through the UI. SUMIDOKU_BASIC_PASSWORD is a legacy alias that applies only when the main variable is unset.

  • Password changes — the settings page requires the current password. Changing it revokes every admin session token.

  • Session tokens — the login page exchanges the admin username and password for a bearer token (30-day rolling expiry) bound to the built-in admin. Login also sets a sumidoku.session cookie containing the same token, with Path=/, HttpOnly, SameSite=Lax and a 30-day maximum age; HTTPS responses add Secure. Browser API requests, including SSE, images and file downloads, use this cookie instead of putting credentials in URLs. Logout and password changes clear it; password changes also revoke every session token as described above. Tracker OAuth callbacks use the same session cookie plus the one-shot state nonce, so the top-level cross-site return can complete; a callback without a session still answers 401.

  • API keys — long-lived bearer credentials used directly as Authorization: Bearer <key>; they act with the built-in admin’s identity and never create session cookies. Create and revoke them in Settings → System → API keys (POST /api/v1/auth/api-keys and DELETE /api/v1/auth/api-keys/{id}). The plaintext key is shown once in the creation response; only its SHA-256 fingerprint is stored (api_key table, migration 0024) together with name, creation time and last-used time. Revoking deletes the fingerprint, so the key dies immediately. Legacy SUMIDOKU_AUTH_API_KEYS and auth.api_keys are no longer accepted; recreate any required keys in the UI.

    Bearer session tokens remain available for CLI and other non-browser clients.

  • JSON backups — plaintext API keys, their fingerprints, and session-token hashes are not exported or restored. Import leaves existing target keys and sessions untouched; on a new instance, log in with its admin password and create new API keys. Source credentials in source settings are separate and may be included in the sensitive backup document.

Notes

  • URL access_token parameters are not accepted. The browser uses the session cookie for all API requests; other clients use the bearer header.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close