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
UserCompanymembership 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 forcesPOST /authenticate/refreshso 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 previousnullpreference), it clears the session and returnscompany_switch_partial_reauthenticateto request a new sign-in. A 401 from refresh clears the session assession_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 companies | X-Company-Id header | Result |
|---|---|---|
| Exactly 1 | Absent | That company is assumed |
| 2 or more | Absent | Operations needing a tenant are rejected |
| Any number | Present and in the linked set | That company is the active context |
| Any number | Present and not linked | 403 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:
| Field | Description |
|---|---|
userId | User identifier |
companyId | Company active in this session |
role | The 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-companyThe 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
| Method | Route | Public | Description |
|---|---|---|---|
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.