Set Up Browser Sessions

Browser clients do not store access JWTs in local storage or application state. Login and refresh responses set HttpOnly cookies, and authenticated requests let the browser send those cookies back to the API.

Sign In

Start with GET /v1/auth/requirements to load registration, password policy, and MFA enforcement settings. Then call POST /v1/auth/login.

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

If MFA enforcement is enabled and the login requires a second step, the first response contains requiresMfa, mfaToken, and mfaMethods. Complete MFA by calling the same endpoint with mfaToken, mfaMethod, and mfaCode.

On success, the API sets access and refresh cookies. The JSON token field is empty for browser session flows.

Call Authenticated Endpoints

Use credentials: 'include' on API calls from browser code:

const response = await fetch(`${apiBaseUrl}/v1/auth/tokens`, {
  credentials: 'include',
});

For POST, PUT, PATCH, and DELETE, the browser request must come from the API origin or from a configured frontend origin. This protects cookie-backed sessions from cross-site request forgery.

Refresh And Logout

Use POST /v1/auth/refresh to rotate the refresh token and set a new access-token cookie.

Use POST /v1/auth/logout to revoke the current refresh token and clear browser session cookies.

Both calls should include credentials:

await fetch(`${apiBaseUrl}/v1/auth/refresh`, {
  method: 'POST',
  credentials: 'include',
});