Skip to content

Company ownership lifecycle ​

This page documents what happens when someone registers, who owns which company, the difference between "the default company" and a company created by its own owner, and who may delete a company.

→ For how each company is isolated as a tenant (JWT, X-Company-Id, assertOwnership()), see Multi-tenancy. For who may assign which role, see Roles and permissions.

CompanyEntity.ownerId — what it is and what it is not ​

Every company has an ownerId field (owner_id, select: false — never returned by the /companies HTTP responses, like UserEntity.password):

  • It holds the userId of whoever created the company (POST /v1/companies or registration with companyName). It may be null (companies created without an associated user, e.g. the seed script).
  • It is not the same as being OWNER in user_companies. ownerId is a fixed pointer to who created the companies row; the owner role in user_companies is a membership that can be added or removed (see Roles and permissions). In practice both match at creation time — the creator is stored as ownerId and added as a member with the owner role in the same operation — but only ownerId survives if that membership is later removed.
  • Today ownerId is used for exactly one thing: GET /v1/companies narrows the list to "the companies they own" when the caller is an OWNER. It is not used for authorization — deleting or editing a company checks membership (assertOwnership()) and role (@Roles(...)), not ownerId.

Registration → owner: the two POST /users paths ​

POST /v1/users is public (the registration step) and always returns an access_token. The optional companyName field decides which path runs:

Without companyNameWith companyName
CompanyJoins the default company, if one existsCreates a new company
Role assignedmemberowner
Atomic?User and membership in separate stepsUser + company + membership in one transaction (DataSource.transaction)
Company ownerIdNot applicable (pre-existing company)The new user's userId
Returned JWTcompanyId/role of the default company (or none, if no company is marked as default)companyId/role: owner of the newly created company

Neither path depends on multi_company mode — a brand-new user has no previous memberships, so the "one user already belongs to a company" restriction never fires during registration itself.

Default company vs owner-created company ​

Two distinct concepts, and not automatic between each other:

Default company (CompanyEntity.isDefault) ​

  • A boolean flag (is_default), false by default on every new company — including the one the seed script creates. No code path sets isDefault to true automatically. Marking a company as "the default company" is a manual operational decision (PATCH /v1/companies/:id { "isDefault": true }, or directly in the database).
  • Effect: when a user registers without companyName, the system looks for the company with isDefault = true and isActive = true and joins them as member. If the user already has a membership, or no company is marked as isDefault, nothing happens — the method returns without error and the user ends up registered with no company.

With no default company configured, simple registration leaves the user orphaned

If nobody marked a company as isDefault = true, a POST /v1/users without companyName creates the account but links it to no company. The user can sign in but sees no company data until someone adds them manually (POST /v1/companies/:id/users) or they accept an invitation. This is intentional (there is no implicit "generic" company) but easy to mistake for a bug in a freshly deployed environment without seeded data.

Owner-created company (companyName at registration, or OWNER/ADMIN via POST /companies) ​

  • It is born without isDefault (stays false) — a normal company, not a candidate to automatically receive users who register without companyName.
  • Its creator is stored in CompanyEntity.ownerId and as an owner member.
  • An OWNER can end up owning several such companies (creating a second one while already in another requires multi_company = true). GET /v1/companies for an OWNER returns every company they own, not only the one selected as the current tenant.

In short: "default" is about how new users without companyName enter; "owner-created" is about who is recorded as the owner of a new company. One company could in theory be both (someone marks an owner-created company as isDefault), but there is no automatic relationship between them.

Who may delete a company ​

DELETE /v1/companies/:id

Rules, from CompaniesController (@Roles(CompanyRole.OWNER)) and CompaniesService.remove() (assertOwnership()):

  1. Only the owner role may delete — not admin, even though admin can create and edit companies (PATCH). There is no "admin may delete when there is no owner" hierarchy: the route guard literally requires owner.
  2. The caller needs an active UserCompany membership in the company they are deleting. Company selection (JWT or X-Company-Id) does not grant access by itself; the current role of that membership is applied. An owner of company A cannot delete company B, even if both carry the same role.
  3. The platform Super Admin role bypasses neither membership nor ownership. A Super Admin can delete a company only if they also hold an active membership with the OWNER role there; their global permission is reserved for explicitly platform-level operations and catalogs.
  4. Deletion is a real DELETE of the companies row, not a soft delete (isActive = false is a different field, managed by PATCH). Associated memberships (user_companies) are deleted by a database-level cascade (onDelete: 'CASCADE').
  5. Deleting a company does not transfer or reassign its ownerId — it simply ceases to exist along with its memberships. There is no "transfer ownership" flow before or during deletion.

Nothing prevents the last company of an owner from being deleted, nor the company marked as isDefault — if that happens, the next registration without companyName simply finds no default company until another is marked.

Active context and last-used company ​

A session's active company and a person's last-used company are different concepts. A Super Admin may select a company for SDK requests via X-Company-Id only if they hold an active UserCompany membership there; that membership's roles and grants apply. The temporary selection creates no membership and does not change users.last_used_company_id.

For a human user, auth.selectCompany() updates users.last_used_company_id via PUT /v1/users/me/last-used-company and requests a forced refresh so the JWT carries the new company and role. The PUT still requires membership; the refresh resolves the context again on the backend. If a refresh fails, the SDK only claims it reverted the change once it has confirmation that the previous preference was restored. Because the API has no operation to store null, a previous null preference cannot be restored; the SDK ends the session with company_switch_partial_reauthenticate and requires a sign-in.

Cross references ​

  • Roles and permissions — who may assign which role to whom.
  • Multi-tenancy — data isolation per company, single vs multi mode.
  • Users — full POST /users contract and the isSuperAdmin flag.
  • Companies — full POST/PATCH/DELETE /companies contract and member management.