#Authentication

V8 Phase 2 (Authentication & Security) is "requirements complete" but not built V8 requirement Planned, not built. sa-central-api-2 has no auth endpoints yet Missing. Endpoint paths below are V7 references, not V8 contracts. V8 paths are decided when Phase 2 is planned.

#Feature list

#Login flow

// 2FA off — POST /login
{"access_token": "eyJ…", "token_type": "Bearer", "expires_in": 1767225600,
 "user": {…}, "organizations": [{…}]}

// 2FA on — token withheld until POST /two-factor-authentication/verify
{"access_token": null, "token_type": null, "expires_in": null,
 "user": {…}, "organizations": null}

#Registration flow

• An organization is not created at registration. V8 requirement
• An initial plan at registration: V7 accepts default_plan (Pro / Standard) and creates Free/trial plans. Decided for V8 on 2026-10-09 (Bhavik): no trial, and no plan is chosen inside the sign-up form. The user signs up, then lands on a Choose a plan step at /billing/plan — so registration itself carries no plan field. See FE: Plans & subscription.
• An invitation code in the URL pre-fills and links the pending membership. V7 only invitation_token
• Dropped from V7: throwaway-email block, Gmail-dot check, device fingerprint. V8 requirement

#OAuth (Google / GitHub)

• Keys are managed in the admin panel, and read from the database until it exists. V8 requirement
• Failure cases: provider disabled ("configuration is disabled" in V7), consent cancelled, email missing from provider, state mismatch. Each returns to /login?error=<code> with a translated message. Assumption error codes still to define.

#Logout

1. FE calls logout, which revokes the token on BE. V8 requirement 2.10
2. FE clears the session cookie / token store, Zustand stores (current organization, cached lists) and any per-user cache.
3. Redirect to /login. Logout links are not prefetched.

#Current user / session restore

• On every protected page load, the app needs current user + organizations to render the shell. V7 has GET /me and GET /auth/user/organizations. V8 needs the same Missing.
• If the token is expired, use the refresh token once (V8 2.9). If that fails, clear the session and go to login with ?next=.

#Session handling (frontend)

Required by project rules: "cookie-based session for SSR", tokens never in client bundles, cookies httpOnly, secure, sameSite=Lax. Required by V8 doc (2026-10-08): Sanctum Bearer tokens only, plus a refresh token Central builds itself.

Recommended (needs approval): a BFF pattern inside Next.js.

• Next.js route handlers (/api/auth/*) call sa-central-api-2 login/refresh/logout and keep the access and refresh tokens in httpOnly cookies.
• Server components and route handlers attach Authorization: Bearer when calling the API. The browser never reads the token.

The alternatives are now down to one bad option. Sanctum SPA cookies was the obvious competitor and the backend has ruled it out itself (1.4, 2026-10-08). A token in memory still conflicts with the cookie rule and loses the session on every reload. So the BFF is not merely preferred — it is what is left. Open question Decision D-1 in Open questions is now only about the response shape and where Next.js keeps the tokens.

#Protected routes

• Public: login, register, verify, forgot/reset, invitation accept, IP-approval result, OAuth callback.
• Logged-in users who open /login or /register are sent to the dashboard.

#Account features (Phase 3, reached from the user menu)

Profile, change email (confirm link to new address + notice to old), change password (logs out other devices), email preferences, delete protection, delete account (password; negative balance must be paid first), 2FA + backup codes (stored encrypted), Google Authenticator (on only after one correct code), IP whitelist (turning it on adds the current IP), login history, account activity, API access on/off, active sessions with log out one/all (new in V8). V8 requirement Phase 3

#Not supported / not decided