Skip to content

Users ​

What this module does ​

It manages the system's user accounts. A user is a person who can authenticate and belong to one or several companies.

Key concepts ​

  • A user has an email, a name and a password.
  • A user can belong to several companies with a different role in each one.
  • Creating a user is public (no authentication required) — it is the registration step.
  • Listing and reading users require authentication (and tenant isolation). PATCH/DELETE additionally require the OWNER or ADMIN role.

Available operations ​

Creating a user (registration) ​

POST /users
{
  "name": "Ana García",
  "email": "ana@company.com",
  "password": "optional, minimum 6 characters"
}

Requires no token. It is the entry point for new users — both public self-registration and an administrator signing someone else up. If the email already exists, it answers 409.

Without companyName, the user joins as member to an active company marked isDefault=true. If there is no active default company, it answers 503, reports that registration is unavailable and creates no account.

A user without a password cannot sign in until one is assigned

password is optional at registration. Without it, the account cannot authenticate until an OWNER/ADMIN sets one with PATCH /users/:id or the user completes the password reset flow.

Response — the created user plus an access_token (a JWT for that new user, intended so the self-registration flow itself can sign in immediately):

json
{
  "id": "uuid",
  "name": "Ana García",
  "email": "ana@company.com",
  "createdAt": "...",
  "updatedAt": "...",
  "access_token": "eyJ..."
}

Do not use access_token when creating a user on someone else's behalf

If an authenticated administrator calls this endpoint to sign another person up, they must discard access_token — storing it would replace their own session with the newly created user's.

Registration as the owner of a new company ​

POST /users
{
  "name": "Ana García",
  "email": "ana@company.com",
  "password": "optional, minimum 6 characters",
  "companyName": "My Company Ltd"
}

When companyName is sent, the user, a new company and their owner membership are created atomically in a single transaction — the user does not join the default company (isDefault=true) as member. The company slug is generated automatically from the name (lowercase, no accents, hyphen-separated); if it already exists, a numeric suffix is appended.

The response's access_token already carries the newly created company's companyId and role: owner, ready to use without a second login.

Without companyName, the behaviour is the one described above: the user joins the active default company as member; if none exists, registration fails with 503 and creates no account.

Listing users ​

GET /users?page=1&limit=20

Returns the users of the session's active company.

If the token has no associated company:

  • Owner or admin → returns every user in the system (global administration view).
  • Any other role (or no role) → returns an empty page, never another tenant's data.

Pagination — page (default 1) and limit (default 20, maximum 100) are optional. The response is an envelope, not a flat array:

json
{
  "data": [/* users on this page */],
  "total": 42,
  "page": 1,
  "limit": 20
}

A page out of range is not an error: it returns data: [] with total reflecting the real count.

Reading a user ​

GET /users/:id

Returns the user only if they have an active membership in the selected company. Without a tenant context or membership, arbitrary ids are not resolved: even a Super Admin must belong to the company to read its users. In any other case it answers 404 — cross-tenant existence is never leaked.

Updating a user ​

PATCH /users/:id
{
  "name": "Ana García López",
  "email": "ana.new@company.com",
  "password": "optional, minimum 6 characters",
  "isSuperAdmin": true
}

All four fields are optional — you can update only the name, only the email, only the password, only the super admin flag, or any combination.

Tenant permissions

Tenant-scoped profile or membership changes require an active membership in the target's company and the corresponding OWNER/ADMIN role; a Super Admin without a membership gains no access through their platform flag. MEMBER/VIEWER receive 403. The scope of privileged API keys follows their separate contract. Global management of the isSuperAdmin flag grants no permission over the rest of the user's data.

password can only be set by an OWNER or ADMIN

If the body includes password and the caller's role (per their JWT) is neither owner nor admin, the request answers 403 Forbidden and nothing is saved.

isSuperAdmin can only be granted or revoked by another super admin

If the body includes isSuperAdmin and the caller is not already a super admin, the request answers 403 Forbidden and nothing is saved. This is intentional: nobody can promote themselves. The system's first super admin is granted by running the seed script (src/database/seed.ts) — see the next section.

Super admin (platform-level role) ​

isSuperAdmin is a boolean flag on the user, independent of any company membership. The flag authorizes operations and catalogues that are explicitly platform-global. It does not allow listing, reading or modifying a tenant company's data, nor does it skip its role permissions. To use a company, a Super Admin needs an active UserCompany membership there and is subject to its role and grants, like any other member. X-Company-Id only selects an active membership; it grants no access.

The flag travels in the JWT as a snapshot from sign-in time, just like role, but it is re-verified against the database on every request that claims it as true — so revoking someone's super admin takes effect on their next request, not when the token expires (up to 90 days).

How the first super admin is granted: by running the seed script with SEED_ADMIN_EMAIL pointing at the account to promote. The script promotes that account idempotently on every run.

Tenant access limit

The header does not authorize access by itself. Any user JWT, including a Super Admin's, needs an active UserCompany membership for the company it names. The current policy rejects selecting a company the user is not a member of and uses their effective role and grants for the selected company.

Deleting a user ​

DELETE /users/:id

Returns 204 No Content when deleted successfully. Requires OWNER or ADMIN (the same gate as PATCH) and the target must belong to the active tenant.

Relationship with companies ​

Users are not directly linked to a company at registration. The link happens at two moments:

  1. Manually — an administrator adds the user to their company from the Companies module.
  2. By invitation — the user accepts an invitation sent by email.

→ See Invitations and Companies for more detail.

Last-used company ​

Session preference of the authenticated user, consumed by the browser SDK to auto-select a tenant after login.

MethodRouteAuthDescription
GET/users/me/last-used-companyUser JWTReturns { companyId } or null
PUT/users/me/last-used-companyUser JWTPersists { companyId } when a membership exists

Storage: the users.last_used_company_id column. Login (POST /authenticate/token) uses this preference when the body carries no companyId (see Authentication).