Skip to main content

Auth, session, and tenant bootstrap

The Academia frontend does not treat authentication as a token-only step. Login, session refresh, tenant context, and role-aware routing all work together to decide where a user lands and which requests the UI can make safely.

Why this page matters​

The main environment and API page already documents the shared client and endpoint families. This page goes one layer deeper into what happens between login and a working dashboard.

Fastest route through this guide​

  1. Read Login bootstrap flow to understand the first request sequence.
  2. Read What the session profile must carry to see the fields the frontend depends on.
  3. Read How tenant-aware routing stays stable to understand the frontend state model.
  4. Continue to Environment and API client if you want the lower-level request and interceptor rules.

Login bootstrap flow​

The login flow begins with:

POST /auth/login

The payload may include:

  • email
  • password
  • tenantDomain

After a successful login, the frontend does not stop at the login response. It follows with a best-effort canonical refresh through the current-user endpoints so the app can work from normalized session data rather than only from the initial token response.

What the session profile must carry​

The current session shape already includes more than identity basics.

Important fields include:

  • accessToken
  • refreshToken
  • user
  • tenantId
  • tenantDomain
  • tenant object with name, domain, and status
  • departmentId
  • roles
  • optional tenantVerification

These fields matter because the frontend uses them for:

  • dashboard routing
  • tenant-aware request headers
  • verification-aware department-head flows
  • realtime authentication context

How tenant-aware routing stays stable​

The frontend preserves tenantDomain in the auth store and can also recover it from persisted auth state when needed.

That stability matters because:

  • the shared API client sends X-Tenant-Domain on upstream calls when available
  • socket connections reuse the same tenant context
  • the app can avoid losing tenant identity when the in-memory store is temporarily empty

If tenant context is missing or stale, the user may appear authenticated while still failing tenant-specific requests. That is why tenant state belongs in the bootstrap model, not only in middleware docs.

Role-aware landing behavior​

Once the authenticated session is available, the frontend can resolve the user's primary role and route into the matching workspace.

Typical targets include:

  • /dashboard/department-head
  • /dashboard/coordinator
  • /dashboard/advisor
  • /dashboard/student
  • /dashboard/evaluator
  • /dashboard/committee-member

This is the practical consequence of the session bootstrap flow: the app needs trustworthy role and tenant state before it can land the user correctly.

Department-head-specific bootstrap rules​

The department head has an extra first-run concern that most other roles do not: verification state.

Because the session profile can carry tenantVerification, the frontend can redirect department heads into verification-specific onboarding instead of pretending that login alone means setup is finished.

That is why department-head onboarding should be documented as:

  1. login success
  2. session refresh
  3. verification-state check
  4. redirect into verification or setup as needed

Mock roles and safe testing​

The current frontend also supports NEXT_PUBLIC_ACADEMIA_MOCK_ROLE for isolated UI preview work.

Use that only when:

  • you are previewing a role surface locally
  • you are not trying to validate real backend-authenticated behavior

Do not use mock-role behavior as evidence that real login, tenant headers, or session bootstrap are correct.

Common mistakes to avoid in the docs​

  • Do not describe login as a one-request finished state. The app still needs canonical session refresh.
  • Do not treat tenant domain as a minor extra field. It is part of request routing and socket context.
  • Do not assume every role boots the same way. Department-head flows include verification-aware routing.
  • Do not use mock-role previews as a substitute for authenticated integration testing.

Best page after this one​

If you want to do next...Go hereWhy
See the shared request and interceptor behaviorEnvironment and API clientIt explains the lower-level client rules behind this bootstrap flow.
See host and middleware tenant handlingMulti-tenancyIt covers the host-derived side of tenant behavior.
See verification-specific first-run behaviorInstitution verification and tenant statusIt explains the special department-head onboarding branch.

Best next reads​