Authentication

Authentication runs on Next.js App Router with Auth.js (NextAuth v5). Users authenticate via OAuth (Google, Facebook) or credentials, with optional 2FA, email verification, and password reset. Sessions are JWTs scoped via cookies on .databayt.org for cross-subdomain SSO.

For provider-specific detail see credentials, oauth, and flow diagrams.

Entry points

USER role redirects to /{locale} (homepage), not /onboarding. Onboarding is reachable only via explicit callbackUrl.

Redirect priority

Decision chain in src/auth.ts redirect callback and src/components/auth/login/action.ts:

1. Callback URL — cookie / URL params / baseUrl params (preserved across OAuth via httpOnly cookie)
2. Explicit relative path from signIn({ redirectTo })
3. Subdomain detection — on a school subdomain → that school's dashboard
4. Smart redirect — decode JWT, look up school, redirect to school dashboard
5. Fallback — main domain dashboard

Session and JWT

Copy// JWT (jwt callback)
token = {
  id: string
  role: UserRole
  schoolId: string | null
  provider: string
  providerAccountId: string
  sessionToken: string
  updatedAt: number
  hash: string
  exp: number
}
 
// Session (session callback)
session.user = {
  id: string
  email: string
  role: UserRole          // Effective role — preview if active
  schoolId: string | null
  isPreviewMode: boolean
}

Session config: strategy: "jwt", maxAge: 24 * 60 * 60 (24h), updateAge: 5 * 60 (5 min in production).

Tenant context

Copyimport { getTenantContext } from "@/lib/tenant-context"
 
const { schoolId, requestId, role, isPlatformAdmin } = await getTenantContext()
// Priority: impersonation cookie → x-subdomain header → session

Two-tier subdomain → schoolId cache: Upstash Redis (5 min, shared) → in-memory Map (1 min, max 100 entries, per-instance fallback). Redis optional. Full detail in multi-tenancy.

Roles

Copyenum UserRole {
  DEVELOPER   // 8 - platform admin (cross-school)
  ADMIN       // 7 - school administrator
  TEACHER     // 6 - teaching staff
  ACCOUNTANT  // 5 - finance staff
  STAFF       // 4 - general staff
  GUARDIAN    // 3 - parent / guardian
  STUDENT     // 2 - enrolled student
  USER        // 1 - default
}

Eight roles total. Hierarchy in src/lib/school-access.ts; must stay in sync with roleRoutes in src/routes.ts. See authorization for feature-level permission checks.

Route protection

Edge middleware decodes JWT, checks roleRoutes, detects subdomain (custom domain → Redis lookup), sets x-subdomain header for downstream consumers.

Copy// Server component
import { auth } from "@/auth"
 
export default async function ProtectedPage() {
  const session = await auth()
  if (!session) redirect("/login")
  return <Dashboard schoolId={session.user.schoolId} />
}

Copy"use client"
 
import { RoleGate } from "@/components/auth/role-gate"
import { useCurrentRole } from "@/components/auth/use-current-role"
import { useCurrentUser } from "@/components/auth/use-current-user"
 
;<RoleGate allowedRole={UserRole.ADMIN}>
  <AdminPanel />
</RoleGate>

Registration paths

Self-enrollment toggle: SchoolBranding.allowSelfEnrollment — enabled gives instant join, disabled creates a pending MembershipRequest.

Preview mode

Lets admins see the UI as another role without changing their actual role. Uses preview-mode and preview-role cookies; session callback overrides role and sets isPreviewMode: true.

Impersonation

DEVELOPERs can impersonate school contexts for debugging. Cookie impersonate_schoolId is httpOnly, secure, 1-hour maxAge. IMPERSONATION_STARTED and IMPERSONATION_STOPPED events are audit-logged. Impersonation takes priority over all other tenant resolution methods.

See also

• Credentials
• OAuth — providers, multi-tenant adapter, cross-subdomain cookies
• Flow diagrams
• Onboarding
• Multi-tenancy