Auth overview

StoryShelf ships one auth engine — @storyshelf/auth on Better Auth. The login page renders one widget per configured method (password, oauth, sso, passkey descriptors). See also Auth concepts.

Choose a method

Type	When to use	Guide
Local accounts	No IdP; invite-only email/password	Local accounts
Social login	GitHub / GitLab / Google / Microsoft / Cognito	Social login
OIDC	Keycloak, Okta, Auth0, Entra, Google Workforce	OIDC
SAML	Enterprise SAML IdP (via samlify, never hand-rolled XML)	SAML
Passkeys	WebAuthn passwordless (second factor / primary)	Passkeys
None	Trusted network / VPN / local dev	Below

Configuration, secrets, and login text are covered in Configuration.

None (default)

With no auth configured, the web UI is open and project roles are not enforced. Fine for local dev (npx storyshelf server init → Which auth? None) or a VPN-protected demo.

Caution

Do not expose an auth-less instance to the public internet — anyone can review, approve, or reject builds.

Secrets

SECRET signs session cookies — generate once, keep stable:

SECRET=$(openssl rand -hex 32)   # ≥ 32 characters, required at boot

Never reuse SECRET for STORYSHELF_ADMIN_TOKEN (site-admin bearer for project creation / purge).

First admin bootstrap

With auth enabled and an empty DB, set STORYSHELF_ADMIN_TOKEN (or ADMIN_TOKEN) — its bearer grants site-admin API access without a session. Creating a project as a logged-in user also records you as that project’s admin.

Project roles, tokens, and public Storybooks

• Roles: viewer / developer / approver / admin per project plus site admin/member — see Roles & tokens.
• API tokens: CLI uses per-project Authorization: Bearer <token> (STORYSHELF_TOKEN) and site-admin tokens — not user login. See Roles and guides above.
• Public Storybooks: viewable without auth when public_branch_regex matches or build.public is set — see Publishing.