Skip to main content

Authentication

The API authenticates with a session cookie, not a bearer token.

There is no Authorization header

Signing in sets an HTTP-only session cookie, and that cookie authenticates every subsequent request. Because it is HTTP-only, client-side JavaScript cannot read it — which is the point. Your client must send cookies (withCredentials, or --cookie/--cookie-jar in curl) rather than construct an auth header.

Signing in​

curl -X POST 'https://<host>/api/v1/auth/login' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'email=user@example.com' \
  --data-urlencode 'password=…' \
  --cookie-jar cookies.txt

On success the response envelope reports status: true and the session cookie is set. Reuse that cookie jar for subsequent calls:

curl 'https://<host>/api/v1/profile/me' --cookie cookies.txt

Multi-factor authentication​

If MFA applies to the account, login does not complete in one step: submit the verification code to the MFA endpoint to finish establishing the session.

curl -X POST 'https://<host>/api/v1/auth/mfa' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'code=123456' \
  --cookie cookies.txt --cookie-jar cookies.txt

Enrolment is a separate pair of calls — one to fetch the secret to enrol against, one to confirm the first code.

TODO

Document the exact parameter names for each auth endpoint, and the response shape that tells a client MFA is required rather than that login failed.

Session lifetime and expiry​

Sessions expire. When a request is rejected for an expired or missing session, the correct client behaviour is to discard local state and re-authenticate — not to retry.

Treat 401 as terminal for the request

Retrying an unauthenticated call with the same cookie will fail identically. Send the user back to sign-in instead.

Authorisation​

Authentication establishes who you are; the role model determines what you may do. A valid session with insufficient permissions still fails — a session is not an entitlement.

Tenant-scoped calls require a tenant role in that specific tenant.

Other credential flows​

The API also exposes registration confirmation, invitation acceptance, password change and password recovery. These follow the same form-encoded, enveloped conventions.

TODO

Document whether long-lived API tokens or service credentials exist for machine-to-machine use. If they do not, say so explicitly here — integrators will ask.

See also​