Skip to main content
Version: v5.0.0

Auth

This page covers application-level configuration for provider access and authentication.

Auth behavior​

  • BASE_URL and AUTH_SECRET are required at startup.
  • Keep AUTH_TRUSTED_ORIGINS empty to trust only BASE_URL.
  • Anonymous auth sessions are disabled by default.
  • Set USE_ANONYMOUS_AUTH_SESSIONS=true to enable anonymous session flows.

Runtime modes​

OpenReader has two common runtime modes:

  • Auth enabled, non-admin user: user account/session features are available, but no admin controls.
  • Auth enabled, admin user: full Settings → Admin access (shared providers + site features).

Admin role​

On a fresh installation, set a one-time first-admin credential before boot:

BOOTSTRAP_ADMIN_EMAIL=owner@example.com
BOOTSTRAP_ADMIN_PASSWORD=<unique-initial-password-at-least-16-characters>

OpenReader creates that account once. Sign in and change the initial password under Settings → Account; the Admin tab appears after the password change. If account email delivery is already enabled, the first sign-in attempt sends a verification link. Follow it before signing in. No configuration edit or restart is needed afterward. The initial password is invalid after the change; removing the seed values later is optional. The email is not an admin allowlist, and changing it later does not alter the role. Existing v4 admins are preserved on upgrade. Additional admins are granted under Settings → Admin → Users.

Admins see dedicated areas for users, providers, account email, instance settings, compute, and maintenance.

  • Shared TTS providers — server-managed TTS provider instances with encrypted keys, visible to all users.
  • Site features — runtime overrides for what were previously build-time public env flags (including account signup availability, default TTS provider, audiobook export, etc.).

Email verification and password recovery​

Account email is opt-in and disabled by default. An administrator configures it under Settings → Admin → Email using a verified Resend sender and a sending-only API key, sends a test, and then explicitly enables it.

When enabled:

  • password registrations receive a one-hour verification link;
  • password sign-in is blocked for existing and new unverified accounts and can resend a fresh verification link;
  • Forgot password? sends a generic acknowledgement whether or not the address exists;
  • reset links expire after one hour, successful resets revoke existing sessions, and the user signs in again;
  • GitHub sign-in and already-active sessions keep their existing behavior.
  • Registered users can request a new address in Settings → Account. The address changes only after the new inbox's verification link is followed.

When disabled, registration and password sign-in retain their previous behavior; verification, email change, and recovery actions are clearly unavailable. Users can still change a known password under Settings → Account. Turning the feature off also prevents queued verification/reset messages from being delivered.

Changing a password signs out other sessions. Admin role changes and signup approval are managed in Admin Panel, not through email lists.

Route behavior​

  • / is a public landing/onboarding page and remains indexable.
  • /app is the protected app home (document list and uploader UI).
  • If a valid session exists (including anonymous), visiting / redirects to /app.
  • Protected app routes continue to require auth; when anonymous sessions are disabled and no session exists, users are redirected to /signin.
  • /verify-email, /forgot-password, and /reset-password are public. Token-bearing pages send a no-referrer policy and are excluded from indexing.

Sync notes​

Auth enabled​

  • Settings and reading progress are saved to the server.
  • Updates are not instant push-based sync; they use normal client polling/refresh behavior.
  • If two devices change the same item around the same time, the newest update wins.

Claim modal note​

  • You may still see old anonymous settings/progress available to claim from older deployments.
  • Legacy unclaimed data is only surfaced through the claim flow; normal authenticated routes are scoped to your current user id.