Skip to content
Leverage AI Developer Support

Auth Overview

Authentication in this repo has separate authorities for web users and CMS operators. Better Auth signs people into the web app. Each Payload CMS signs operators into its own admin panel with native Payload users.

Core Model

Section titled “Core Model”
  • Better Auth is the canonical web-app auth authority.
  • web and web-token-replacer use Better Auth for email/password, request-access completion, and workforce SSO.
  • Both Nuxt web-user apps share @repo/nuxt-auth-layer for sign-in pages, session state, route middleware, onboarding pages, auth composables, and auth BFF routes.
  • Auth screen branding and shell layout are app-local authUi config on top of the shared layer; apps may set labels, mark text, light/dark logo asset URLs, and split-versus-centered layout without forking auth behavior.
  • cms-customer uses native Payload CMS Users for operator login and shows Better Auth users only through a read-only Web App Users mirror.
  • cms-leverage uses separate native Payload users for Leverage-owned operators.
  • Both CMS apps require Payload email verification before login.
  • api validates Better Auth-backed session state for Mastra-facing runtime behavior.
  • User-owned API keys use Better Auth’s API Key plugin and authenticate product API requests with x-api-key.

Web Sign-In Vs CMS Operator Sign-In

Section titled “Web Sign-In Vs CMS Operator Sign-In”
  • apps/web is the main product workspace.
  • apps/web-token-replacer is a bare authenticated shell for the future token replacer product.
  • Both Nuxt apps use the same web Better Auth sign-in policy and user store.
  • cms-customer and cms-leverage are operator-facing Payload admin surfaces.
  • CMS operator accounts are separate from web users, even when they share the same email address.
  • Workforce SSO is web-auth-owned in this slice; CMS SSO is not part of the active implementation.

Request Access And Bootstrap

Section titled “Request Access And Bootstrap”
  • Public email/password sign-up is not the model here.
  • Web onboarding goes through request access, admin review, and completion.
  • Customer CMS admins can create Web Access Requests, but that is an Auth-backed invitation command that sends a completion invitation. It does not directly create a Better Auth user.
  • Customer CMS admins cannot directly delete Web Access Requests; correction, cancellation, revocation, anonymization, or retention cleanup must be Auth-owned so audit history and completion-token state stay coherent.
  • Native Payload’s first-user bootstrap auto-verifies the first CMS user. Production bootstrap should be controlled through the operator runbook.
  • Production CMS runtime refuses disabled Payload email; verification and password-reset delivery must be SMTP-ready before operator handoff.

Deployment-Scoped Sign-In Policy

Section titled “Deployment-Scoped Sign-In Policy”

Allowed web sign-in methods are configured through auth-side environment variables. The current model is deployment-scoped rather than tenant-resolved at request time.

Workforce SSO provider ids stay separate from connector/social OAuth provider ids for every provider family. Workforce sign-in can use ids such as google-sso and microsoft-sso; connector-linked accounts can use ids such as google and microsoft. That separation prevents connector tokens from becoming sign-in providers and keeps *_SSO_* env vars from crossing into connector OAuth setup.

Better Auth owns linked-account uniqueness for connector/social OAuth: the same external provider account pair (providerId + accountId) may belong to only one Better Auth web user unless a future app-level sharing model is explicitly accepted.

Who Owns What

Section titled “Who Owns What”
Area Primary owner
Better Auth authority, web sessions, SSO policy apps/auth
Shared Nuxt auth UI/session/runtime code packages/nuxt-auth-layer
Main user workspace apps/web
Token replacer authenticated shell apps/web-token-replacer
Customer CMS operator login and CMS users apps/cms-customer
Better Auth web-user read-only mirror in CMS apps/cms-customer
Leverage CMS operator login apps/cms-leverage
Session validation for Mastra runtime access apps/api
Screenshot Placeholder
Web auth and native CMS auth boundaries

Replace later with a screenshot or diagram showing web Better Auth, customer CMS users, and the Web App Users mirror.

Which Files Matter

Section titled “Which Files Matter”
File What it helps you answer
apps/auth/.env.example Which auth-side env groups control web sign-in behavior
packages/nuxt-auth-layer Shared Nuxt auth pages, middleware, stores, and routes
apps/web-token-replacer/.env.example Token replacer local auth URL and trusted-origin notes
apps/cms-customer/README-auth-integration.md Native customer CMS auth and Better Auth web-user mirror
docs/features/authentication/spec.md The full end-state auth model and constraints
packages/contracts/src/auth/apiKeys.ts User API-key management and product header contracts
docs/features/token-replacer/spec.md Token replacer authenticated shell scope
LIMITATIONS.md Mirror and Payload verification limitations
packages/contracts/src/auth/signInPolicy.ts The web sign-in policy transport contract
Section titled “What To Read Next”

Helpful External Docs

Section titled “Helpful External Docs”