Companies
What this module does
It manages the system's companies (tenants) and their members. Each company is an independent workspace: its data, users and configuration are separated from those of other companies.
Key concepts
- A company has a name, a unique slug, an active/inactive state and, optionally, the issuer's fiscal identity: legal name (
fiscalName), tax identifier (taxId), fiscal address (fiscalAddress) and country/jurisdiction (fiscalCountryCode, ISO 3166-1 alpha-2). Those fields are the source of truth for billing and for when Nimobase bills the tenant (recipient = the company's fiscal details). The response includesfiscalEmissionReadyandmissingFiscalFields: without them complete, no fiscal document can be issued (saving the company or drafts still works). - Each company has members — users with a role assigned inside that company.
- Roles determine what each member can do. → See Roles and permissions
Company management
Creating a company
POST /companies
{
"name": "Acme Corporation",
"slug": "acme", ← lowercase letters, digits and hyphens only
"isActive": true,
"fiscalName": "Acme Corporation S.L.", ← optional
"taxId": "B12345678",
"fiscalAddress": "Calle Mayor 1, 28013 Madrid",
"fiscalCountryCode": "ES"
}Requires the owner or admin role. The fiscal fields are optional at creation; if missing, fiscalEmissionReady is false until they are completed with PATCH.
Whoever creates the company automatically becomes its OWNER. If multi_company=false (single company mode) and the creator already belongs to another company, creation is rejected with 409 Conflict — no orphan company is ever saved. To let one user create and belong to several companies, first set multi_company=true.
In addition, if the owner already subscribed to a billing plan with a max_companies limit (see Billing) and has reached that limit, creation is also rejected with 409 Conflict — with a different message that names the current plan and suggests an upgrade, so it can be told apart from the multi_company rule above. This limit is resolved from the company (or companies) the owner already holds with an active subscription; an owner's first company is never blocked by this rule, and if the owner has no plan at all it does not apply either.
Listing, reading and updating
GET /companies ← active companies visible to the caller (see below)
GET /companies/:id ← one specific company (assertOwnership)
PATCH /companies/:id ← update name, slug or state
DELETE /companies/:id ← delete (returns 204)GET /companies/:id requires an active UserCompany membership in that company (assertOwnership): 403 if the caller has no membership; 404 if the company does not exist (after passing ownership). The Super Admin flag does not allow reading other companies.
GET /companies is narrowed by active memberships and credentials:
- Super Admin → only companies where they have an active
UserCompanymembership; without a membership they do not receive the global directory and cannot manage app client links with that company. - Human JWT with no company selected (there is a
userId, it is not an API key) → only the companies where they have an active membership; if they have none, an empty page. They never receive the platform directory. - Service accounts / tooling (no tenant and no human
userId) → every active company, only when their machine credential contract authorizes it; this separate access is not obtained through a user's Super Admin role. - OWNER → companies where they hold an active membership with the OWNER role, not only the company currently selected as tenant.
CompanyEntity.ownerIdalone does not replace membership. This enables the case of an owner with several companies (see Users → Registration as the owner of a new company and the multi-company plan, not implemented yet). If for some reason the token carries nouserId(the uncommon case of service accounts with an owner role), the fallback applies: only the current company (or the service account path when there is no tenant either). - Any other role (ADMIN, MEMBER, VIEWER) → only companies with an active membership in their scope. They gain no visibility over companies they do not belong to, not even when the owner of those companies is the same person administering them.
The Super Admin role does not grant the company directory. Human users only see companies with an active membership; tooling principals without a human identity follow explicit, separate machine contracts.
Pagination — GET /companies accepts ?page (default 1) and ?limit (default 20, maximum 100). The response is an envelope, not a flat array:
{
"data": [/* companies on this page */],
"total": 12,
"page": 1,
"limit": 20
}A page out of range is not an error: it returns data: [] with total reflecting the real count.
PATCH /companies/:id requires owner or admin and accepts partial fields; isActive is also optional. It can update the name, slug, state and fiscal identity (fiscalName, taxId, fiscalAddress, fiscalCountryCode). DELETE /companies/:id requires owner only — an admin can edit the company but not delete it. Both also require the caller to belong to that company (assertOwnership()); the global Super Admin role replaces neither the active membership nor the company role.
Member management
Seeing who belongs to a company
GET /companies/:id/usersReturns the member list already "flattened" — id is the user id (not the membership row id), along with name, email and role:
[
{
"id": "user-uuid",
"name": "Ana García",
"email": "ana@company.com",
"role": "member"
}
]Adding a member
POST /companies/:id/users
{
"userId": "user-uuid",
"role": "member" ← owner | admin | member | viewer
}It answers with the same flattened shape ({ id, name, email, role }, with id = user id) so the UI can paint the new member without reloading the list.
Role hierarchy when assigning a role
Both owner and admin can call this endpoint, but they cannot grant the same roles:
ownermay assign any role (owner,admin,member,viewer).adminmay assign onlymemberorviewer. If anadmintries to assignowneroradmin, the request answers 403 Forbidden — even though their own role does pass the route guard (OWNER, ADMIN), the role they are trying to grant is not allowed for them. This prevents anadminfrom promoting themselves (or anyone else) toowner/admin.
A super admin (platform role, see Users → Super admin) bypasses this restriction entirely, just as it does with assertOwnership() — they can assign any role even when their token carries no company role.
If that company subscribed to a billing plan with a max_users limit (see Billing) and has reached that limit, adding one more member is rejected with 409 Conflict, with a message that names the current plan and suggests an upgrade. Unlike max_companies (resolved at the owner level, aggregating all their companies), max_users is resolved directly against this company: the count is the company's current number of members versus the max_users of its own active subscription. A company with no plan at all is unaffected.
If the company has a resale plan assigned by its reseller (see Owner plans), that plan governs instead: the resale plan's max_users wins (a plan that does not declare max_users at all blocks the addition, it does not leave it unlimited), and the reseller's shared pool must also still have room. With no resale plan assigned, the platform plan check described above applies unchanged.
Single company mode
If the system is configured for single company mode (multi_company = false), a user can belong to only one company. Trying to add them to a second one returns 409 Conflict — the same code that company creation uses for this same business rule — with a message indicating that multi_company=true must be enabled to allow it.
Removing a member
DELETE /companies/:id/users/:userIdRemoves the user from the company. The user still exists in the system; they only lose access to this company.
Role hierarchy and the last OWNER
Removal applies the same hierarchy as adding (assertCanAssignRole). An admin may only remove members with the member or viewer role (removing an owner or admin → 403 Forbidden). An owner with an active membership may remove any role, except when they are the company's last owner → 409 Conflict (Cannot remove the last OWNER from a company).
Usual flow for adding members
There are two ways to bring someone into a company:
- Directly — an admin adds the user if their account already exists (
POST /companies/:id/users). - By invitation — a token is emailed and the user accepts it. → See Invitations