#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. V8 hasn't decided Open question.
• 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 /[locale]/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 /[locale]/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: Passport bearer + refresh tokens.

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.

Alternatives (Sanctum SPA cookies, or a token in memory) conflict with the Passport decision or the cookie rule. Open question Decision D-1 in Open questions.

#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