Authentication & sessions

These variables govern authentication: how access and refresh tokens are signed and how long they live, how WebAuthn (passkeys / hardware keys) is bound to your domain, and how single sign-on and social login are configured. The single most important value is JWT_SECRET — under production a weak or default secret is a fatal boot guard, as described in Configuration overview.

JWT_SECRET=replace-with-a-long-random-secret-at-least-32-bytes
JWT_TTL=12h
REFRESH_TTL=30d
RP_ID=vault.example.com
RP_NAME=VaultTerm
RP_ORIGIN=https://vault.example.com
[email protected]

Tokens & sessions

Variable	Type	Default	Description
JWT_SECRET	string (required)	(dev default)	Signing secret; must be at least 32 bytes and not the dev default under production (fatal boot guard otherwise).
JWT_TTL	string	12h	Web access token lifetime.
DEVICE_ACCESS_TTL	string	15m	Short-lived access token for native clients.
REFRESH_TTL	string	30d	Device refresh token lifetime.
REFRESH_REQUIRE_DEVICE_SIG	boolean (0/1)	0	Require an Ed25519 device signature on refresh (reuse detection).
TENANT_STEPUP_TTL_SEC	number	300	Freshness window for sensitive actions (step-up re-authentication).
AUTH_RATE_MAX	number	30	Max requests per window on unauthenticated auth endpoints.
AUTH_RATE_WINDOW_MS	number	60000	Auth rate-limit window.

Web sessions use the short-lived JWT_TTL access token; native clients pair an even shorter DEVICE_ACCESS_TTL access token with a long-lived REFRESH_TTL refresh token. Turning on REFRESH_REQUIRE_DEVICE_SIG requires each refresh to carry an Ed25519 signature from the registered device, so a stolen refresh token alone cannot mint new access tokens. TENANT_STEPUP_TTL_SEC is the window after a step-up re-auth during which sensitive actions are permitted without prompting again.

WebAuthn

Variable	Type	Default	Description
RP_ID	string	localhost	WebAuthn relying-party domain (registrable domain only, no scheme or port).
RP_NAME	string	VaultTerm	WebAuthn display name shown during registration.
RP_ORIGIN	comma-separated	(dev localhost origins)	Allowed WebAuthn origins (HTTPS, or localhost).

RP_ID must be the registrable domain (for example vault.example.com, never a URL with a scheme or port), and every origin a user authenticates from must appear in RP_ORIGIN. Passkeys are bound to the relying party, so changing RP_ID invalidates previously registered credentials — set it correctly before users enroll.

SSO & social login

Variable	Type	Default	Description
SSO_ADMIN_EMAILS	comma-separated	(empty)	Emails allowed to configure per-org OIDC/SAML providers; empty locks the provider-config endpoints.
APPLE_TEAM_ID	string	(empty)	Sign in with Apple team id.
APPLE_KEY_ID	string	(empty)	Apple .p8 signing key id.
APPLE_PRIVATE_KEY	PEM	(empty)	Apple .p8 private key; empty disables Apple sign-in.

SSO_ADMIN_EMAILS gates who can set up enterprise identity providers for an organization; leave it empty to lock provider configuration entirely. The Apple variables together enable Sign in with Apple — all three must be present, and APPLE_PRIVATE_KEY empty disables it. For enterprise IdP and directory sync, see SSO & SCIM.

If your IdP or metadata endpoint resolves to a private address, remember the egress guard: EGRESS_ALLOW_PRIVATE=1 must be set or the server-side fetch is blocked under production (see Core & database configuration).