Authentication

Authentication provider

MUZE uses better-auth for authentication. It is configured as an Express middleware handler mounted directly on the NestJS application at /api/auth. better-auth stores sessions and user records in the same PostgreSQL database via @better-auth/prisma-adapter.

Key design decisions

Decision	Rationale
Session-based, not JWT	Sessions are stored server-side in PostgreSQL. The browser holds an HTTP-only cookie. No token refresh logic needed.
Self-sign-up disabled	`disableSignUp: true`: portal accounts are created by Muze Admin only via Account Management.
No OAuth/SSO	Authentication is email + password only. No corporate identity provider integration.
Cross-site cookies	Production uses `SameSite=None; Secure` because frontend (Firebase) and backend (Render) are on different origins.

In production, better-auth sets these cookie attributes:

better-auth.session_token: <encrypted-token>
  HttpOnly: true
  SameSite: None
  Secure: true
  Path: /

In development, the default SameSite: Lax is used.

Auth endpoints (better-auth built-in)

All auth endpoints live under /api/auth (outside the /api/v1 prefix):

Endpoint	Method	Purpose
`/api/auth/sign-in`	POST	Email + password sign-in
`/api/auth/sign-out`	POST	Destroy session
`/api/auth/forgot-password`	POST	Send password reset email
`/api/auth/reset-password`	POST	Set new password via reset token
`/api/auth/get-session`	GET	Return current session (used by frontend)

Session validation flow

Every authenticated request goes through SessionGuard: The SessionGuard calls authService.getSession(request.headers) which internally calls better-auth’s getSession() with the request headers. This queries the Session table in PostgreSQL to validate the token.

Password management

Passwords are hashed by better-auth using industry-standard algorithms (bcrypt by default)
Password reset emails contain a token that links to /reset-password?token=...
When a password is reset via the invite flow, the user’s emailVerified flag is set to true
There are no password complexity requirements enforced beyond what better-auth provides by default

What MUZE does not support

No multi-factor authentication (MFA)
No OAuth / social login
No SSO / SAML / OIDC
No API key authentication
No service-to-service authentication (all API calls are browser-initiated)
No session rotation on privilege escalation
No concurrent session limits

Overview

System Architecture

Security

Business Engines

Notifications & Reports

Data

Operations

Engineering

Authentication provider

Key design decisions

Auth endpoints (better-auth built-in)

Session validation flow

Password management

What MUZE does not support

​Authentication provider

​Key design decisions

​Session cookie configuration

​Auth endpoints (better-auth built-in)

​Session validation flow

​Password management

​What MUZE does not support

Authentication provider

Key design decisions

Session cookie configuration

Auth endpoints (better-auth built-in)

Session validation flow

Password management

What MUZE does not support