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
userIdof whoever created the company (POST /v1/companiesor registration withcompanyName). It may benull(companies created without an associated user, e.g. the seed script). - It is not the same as being
OWNERinuser_companies.ownerIdis a fixed pointer to who created thecompaniesrow; theownerrole inuser_companiesis a membership that can be added or removed (see Roles and permissions). In practice both match at creation time — the creator is stored asownerIdand added as a member with theownerrole in the same operation — but onlyownerIdsurvives if that membership is later removed. - Today
ownerIdis used for exactly one thing:GET /v1/companiesnarrows the list to "the companies they own" when the caller is anOWNER. It is not used for authorization — deleting or editing a company checks membership (assertOwnership()) and role (@Roles(...)), notownerId.
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 companyName | With companyName | |
|---|---|---|
| Company | Joins the default company, if one exists | Creates a new company |
| Role assigned | member | owner |
| Atomic? | User and membership in separate steps | User + company + membership in one transaction (DataSource.transaction) |
Company ownerId | Not applicable (pre-existing company) | The new user's userId |
| Returned JWT | companyId/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),falseby default on every new company — including the one the seed script creates. No code path setsisDefaulttotrueautomatically. 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 withisDefault = trueandisActive = trueand joins them asmember. If the user already has a membership, or no company is marked asisDefault, 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(staysfalse) — a normal company, not a candidate to automatically receive users who register withoutcompanyName. - Its creator is stored in
CompanyEntity.ownerIdand as anownermember. - An
OWNERcan end up owning several such companies (creating a second one while already in another requiresmulti_company = true).GET /v1/companiesfor anOWNERreturns 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/:idRules, from CompaniesController (@Roles(CompanyRole.OWNER)) and CompaniesService.remove() (assertOwnership()):
- Only the
ownerrole may delete — notadmin, even thoughadmincan create and edit companies (PATCH). There is no "admin may delete when there is no owner" hierarchy: the route guard literally requiresowner. - The caller needs an active
UserCompanymembership in the company they are deleting. Company selection (JWT orX-Company-Id) does not grant access by itself; the current role of that membership is applied. Anownerof company A cannot delete company B, even if both carry the same role. - 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.
- Deletion is a real
DELETEof thecompaniesrow, not a soft delete (isActive = falseis a different field, managed byPATCH). Associated memberships (user_companies) are deleted by a database-level cascade (onDelete: 'CASCADE'). - 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 /userscontract and theisSuperAdminflag. - Companies — full
POST/PATCH/DELETE /companiescontract and member management.