Skip to main content

Authentication and Session

Audience: Developers

The user REST API uses a short-lived JWT access token. Browser sessions are restored with a server-managed HttpOnly refresh cookie. Measurement x-api-key authentication is separate from this user session.

Login​

POST /auth/login
Content-Type: application/json

{
  "email": "user@company.example",
  "password": "<user's password>"
}

A successful JSON response includes access_token, active tenantId when present, memberships and platform role. The server also sets the refresh_token cookie. HttpOnly, Secure and SameSite behavior follows the installation's server configuration; the cookie is not exposed to JavaScript.

The access token contains sub, company/role context, session version sv, jti, issue and expiry times. The default access lifetime is 15 minutes and is server-configurable. A token's role snapshot is not permanent authority; the server checks current membership, role and session status.

Protected call​

GET /strategic-cycles
Authorization: Bearer <access_token>
X-Tenant-ID: <tenant_id>

For a company-scoped call, send a company ID you are authorized to use. Platform-scoped endpoints do not always need a company header. Changing a token/header to another company does not grant access.

GET /auth/profile returns account/membership context; GET /auth/my-tenants returns accessible companies. Switch with POST /auth/switch-tenant and targetTenantId in the body; use the new access token and company context returned together.

Restore the session​

POST /auth/session requires a valid refresh cookie, not an access token. A browser client must enable cookie sending for the request. A successful response returns a new access_token and rotates/sets the refresh cookie.

If an access token is still valid, POST /auth/refresh with the Authorization header produces a new token. An expired token cannot renew itself at that endpoint; use the refresh-cookie flow or sign in again.

Logout​

  • POST /auth/logout ends the valid access token and any refresh session.
  • POST /auth/session/logout revokes the refresh session and clears its cookie even when the access token is absent/expired.
  • The client must also clear its in-memory token and user context.

Registration and Google sign-in​

Public registration through POST /auth/register is SaaS-only and unavailable on-prem. Google sign-in is available when enabled with a client ID in Platform Settings. Google sign-in does not bypass memberships/roles, account status or license rules.

Errors and secure use​

  • 401: Invalid token/cookie or ended session. Sign in again if restoration also fails.
  • 403: The session may be valid, but operation, company/record or license scope is unsuitable. Retrying with a new token does not grant authority.
  • 429: Authentication endpoint rate limit exceeded; bound client retries.

Keep the access token in client memory and the refresh cookie inaccessible to JavaScript. Use HTTPS. Keep tokens, passwords and cookies out of logs, URL parameters and support records.

See also​