Skip to content

Authentication ​

What this module does ​

It manages access to the system. Any user or application that wants to use the API must come through here first to obtain an access token (JWT).

Authentication flows ​

1. User login ​

The most common flow. The user sends their email and password and receives a token.

POST /authenticate/token
{
  "username": "user@company.com",
  "password": "their-password",
  "companyId": "optional-uuid"  ← if they belong to several companies
}

Response: { access_token, refresh_token }. The access JWT authenticates requests; the refresh JWT (tokenType: refresh, longer TTL) only serves to renew the session through POST /authenticate/refresh — it is not valid as Authorization: Bearer.

Invalid credentials → 401 Unauthorized with the generic message Invalid credentials (never revealing whether the email or the password failed).

If the user belongs to several companies and does not send companyId, the system automatically selects the last company used by that user (if they are still a member); if there is no known last-used company, it picks the first membership by join order (createdAt ASC). That choice is stored in users.last_used_company_id for the next login.

1b. Renewing the session (refresh) ​

When the access token expires or is about to expire, the client (browser SDK) sends the refresh JWT in the body:

POST /authenticate/refresh
{
  "refresh_token": "<refresh-jwt>"
}

Response: a new { access_token, refresh_token } pair. An invalid or expired token, or an access JWT passed as a refresh → 401 Unauthorized. Public; rate limited to 20 requests/min per IP. App client logins (POST /authenticate/apps) do not issue a refresh token.

Custody: the browser SDK keeps the access and refresh tokens in memory only on the instance; the host does not persist them as a source of truth and does not use HttpOnly cookies for this contract. After a 401 from refresh, getSnapshot() becomes unauthenticated and the host must sign in again.

Last-used company (SDK contract) ​

The browser SDK can read and persist the user's active company:

GET /users/me/last-used-company
→ { "companyId": "uuid" | null }

PUT /users/me/last-used-company
{ "companyId": "uuid" }
→ { "companyId": "uuid" }

Requires a user JWT. PUT answers 403 if the user is not a member of that company. After a successful login (with or without companyId in the body), the API also updates the last-used company.

auth.selectCompany(companyId) and its alias auth.changeCompany(companyId) keep the same public signature, but the SDK applies two different semantics internally:

  • Super Admin: may select a company only if they hold an active UserCompany membership there; their current role and grants apply. The context switch does not change the user's preference and does not require renewing the JWT.
  • Human user: reads the previous preference, stores it with PUT, and forces POST /authenticate/refresh so the new JWT carries the selected company and role. If the refresh fails, the SDK restores a non-null previous preference when it can verify it; if it cannot restore it (including a previous null preference), it clears the session and returns company_switch_partial_reauthenticate to request a new sign-in. A 401 from refresh clears the session as session_expired.

SDK selections are processed in order. A pending operation is cancelled if login/register, logout, clearSession or clearActiveCompany changes the session generation. A selection does not turn a super admin's active company into a membership, and the API does not relax the membership check on the PUT endpoint.

2. Application login ​

For services or automated processes (workers, integrations) that need API access without a human user behind them.

POST /authenticate/apps
{
  "clientId": "client-id",
  "clientSecret": "client-secret"
}

Authorized clients are created beforehand with POST /authenticate/authorized-client?magicWord=<word> (CLI/script use). The clientSecret is generated randomly and shown once in the creation (or rotation) response; the database stores only its hash, never the plaintext value. If the magic word does not match (or is missing), the API answers 401 Unauthorized with the generic message Invalid credentials — not a 200 with a text body.

Rotating an authorized client's secret ​

A platform super admin (isSuperAdmin === true) can rotate the clientSecret of an existing client without recreating it — useful when the secret leaked or simply needs periodic renewal.

POST /authenticate/authorized-clients/:id/rotate
Authorization: Bearer <super-admin-token>

Response: the same clientId with a new clientSecret (visible only once, exactly like client creation). The previous secret stops working immediately — there is no grace period. JWTs already issued with the old secret remain valid until they expire on their own; this action only blocks new login attempts with the old secret.

Super admin only

Any other authenticated user receives 403 Forbidden. Rotating an id that does not exist returns 404.

Managing app clients from the dashboard (list, create, delete) ​

Beyond creation through magicWord (CLI/script use) and the rotation above, a super admin can manage app clients entirely from the dashboard, without the magicWord:

GET /authenticate/authorized-clients
Authorization: Bearer <super-admin-token>

Returns the full list (id, clientId, name, createdAt), never exposing the secret hash. An empty list when there are none yet.

POST /authenticate/authorized-clients
Authorization: Bearer <super-admin-token>
{
  "name": "my-service"
}

Creates an app client like the magicWord path, but authenticated by JWT instead of a magic word. The clientSecret is shown once in the response, exactly as with magicWord creation or rotation.

DELETE /authenticate/authorized-clients/:id
Authorization: Bearer <super-admin-token>

Permanently deletes the app client (204). JWTs already issued for that clientId remain valid until they expire on their own — there is no retroactive revocation, same as with rotation. A login attempt with the deleted clientId fails with the same 401 as a clientId that never existed.

Linking companies to an app client ​

The app client object is global, but its associations with companies are tenant-scoped. A Super Admin can read or change a link only if they hold an active membership with the OWNER/ADMIN role in that company; the list is limited to their own memberships. The association is re-evaluated for subsequent requests. The tokenType: app JWT still queries active links live; with no linked companies it authenticates but cannot operate on tenant data (hard cutoff).

Active company context (the same RequestContext / getTenantId() as the other actors):

Linked companiesX-Company-Id headerResult
Exactly 1AbsentThat company is assumed
2 or moreAbsentOperations needing a tenant are rejected
Any numberPresent and in the linked setThat company is the active context
Any numberPresent and not linked403 Forbidden
GET /authenticate/authorized-clients/:id/companies
Authorization: Bearer <super-admin-token>
POST /authenticate/authorized-clients/:id/companies
Authorization: Bearer <super-admin-token>
{
  "companyId": "company-uuid"
}
DELETE /authenticate/authorized-clients/:id/companies/:companyId
Authorization: Bearer <super-admin-token>

Super admin only

The company-linking routes (like listing, creating and deleting app clients) answer 403 Forbidden when the caller is not a platform super admin.

Linking my company to an app client (OWNER/ADMIN) ​

An OWNER or ADMIN can link only their own active company to an app client they already know by its public clientId. There is no global app client listing for these roles, nor any way to see or modify other companies linked to the same client.

POST /authenticate/app-clients/:clientId/company
Authorization: Bearer <owner-or-admin-token>

No body: the company is taken from the JWT's tenant context. Idempotent if already linked. 404 if the clientId does not exist; 403 if the role is not OWNER/ADMIN.

DELETE /authenticate/app-clients/:clientId/company
Authorization: Bearer <owner-or-admin-token>

Unlinks only the active company (204). The client's other companies are untouched.

The JWT token ​

The token contains:

FieldDescription
userIdUser identifier
companyIdCompany active in this session
roleThe user's role in that company (owner, admin, member, viewer)

Important

The token keeps a snapshot of the role and company at sign-in time, but for any tenant-scoped operation the server must check the current membership and that company's current role and grants. Revoking a membership or changing its permissions must affect the following requests.

Selecting a company without signing in again ​

A user JWT can select another company where it holds an active UserCompany membership using the header:

X-Company-Id: uuid-of-the-other-company

The server validates the membership before granting tenant-scoped context and applies its current role and grants. The platform Super Admin role does not allow selecting companies the user does not belong to; a company without an active membership is denied. Without the header, the JWT's companyId also requires an active membership.

An app client can select only a company actively linked to that client. API keys remain bound to their company and ignore this header to widen their scope. See Multi-tenancy.

I forgot my password ​

From the login screen, a user who does not remember their password can request a reset link without being authenticated.

1. Request the reset ​

POST /authenticate/forgot-password
{
  "email": "user@company.com"
}

Response: always the same, whether or not an account exists with that email — for security, this endpoint never reveals whether an address is registered. If the email exists, a message is sent with a link of the form https://your-domain/reset-password?token=.... The link expires after a few hours (configurable, 2 by default).

2. Set the new password ​

POST /authenticate/reset-password
{
  "token": "token-received-by-email",
  "newPassword": "new-password"
}

The token can be used only once. If it expired, was already used, or does not exist, the request is rejected with an error. The password update and marking the token as used happen in the same database transaction (with row locking on Postgres), so two concurrent requests with the same token cannot both complete. Resetting the password also invalidates any other pending reset link for that same user, for security.

TIP

This is different from an OWNER/ADMIN changing another team member's password through PATCH /users/:id — that is a separate administrative flow, not the self-service one described here.

Endpoints ​

MethodRoutePublicDescription
POST/authenticate/token✅User login — rate limited to 5 requests/minute per IP
POST/authenticate/refresh✅Renew access/refresh with refresh_token — rate limited to 20 requests/minute per IP
POST/authenticate/apps✅Application login
POST/authenticate/authorized-client✅ (?magicWord=; 401 if wrong)Create an authorized client
POST/authenticate/authorized-clients/:id/rotate❌ (super admin only)Rotate an authorized client's clientSecret
GET/authenticate/authorized-clients❌ (super admin only)List every app client (without exposing the secret hash)
POST/authenticate/authorized-clients❌ (super admin only)Create an app client via JWT, without magicWord
DELETE/authenticate/authorized-clients/:id❌ (super admin only)Permanently delete an app client
GET/authenticate/authorized-clients/:id/companies❌ (JWT + OWNER/ADMIN member)List only company links where the actor holds an active membership
POST/authenticate/authorized-clients/:id/companies❌ (JWT + OWNER/ADMIN member)Link a company where the actor holds an active membership
DELETE/authenticate/authorized-clients/:id/companies/:companyId❌ (JWT + OWNER/ADMIN member)Unlink a company where the actor holds an active membership
POST/authenticate/app-clients/:clientId/company❌ (OWNER/ADMIN)Link the active company to the app client
DELETE/authenticate/app-clients/:clientId/company❌ (OWNER/ADMIN)Unlink the active company from the app client
POST/authenticate/forgot-password✅Request a password reset — rate limited to 5 requests/minute per IP
POST/authenticate/reset-password✅Set a new password with the received token

Rate limiting

The system's most sensitive public endpoints (login, password reset request, public user creation in POST /users, and the webhook receiver in POST /webhooks/:provider) answer 429 Too Many Requests when the per-IP limit is exceeded within a 1-minute window. This protects against brute-force attacks and automated abuse.