Onboarding and Session Bootstrap

Use this flow for browser clients.

1. Load Auth Requirements

Call GET /v1/auth/requirements before showing registration or login forms. The response includes whether registration requires admin approval, whether MFA is enforced for password login, and the active password policy.

2. Register Or Login

Register with POST /v1/auth/register. If restricted registration is enabled, the account is created pending approval and no session cookies are issued.

Login with POST /v1/auth/login:

const response = await fetch(`${apiBaseUrl}/v1/auth/login`, {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ usernameOrEmail, password }),
});

If requiresMfa is true, prompt for the selected MFA method and call POST /v1/auth/login again with the returned mfaToken. When MFA enforcement is disabled, password login can complete without this second step.

3. Use The Cookie Session

After successful login or MFA completion, the API sets the browser session cookies. The response body contains the user profile and admin role, but not a readable access token.

Use credentials: 'include' on subsequent API calls.

4. Refresh

Call POST /v1/auth/refresh before or after a 401 caused by access-token expiry. The API rotates the refresh token and sets a new access-token cookie.

If the response includes X-Auth-Error, treat the session as invalid and return the user to login.

5. Logout

Call POST /v1/auth/logout with credentials included. The API revokes the refresh token and clears session cookies.