Roles and permissions
How roles work
Each user has a different role in each company they belong to. The role is set when the user is added to the company (manually or by invitation) and determines what they can do inside it.
This page covers the hierarchy of who may assign which role to whom. For who ends up owning a new company, the difference between the default company and an owner-created company, and who may delete a company, see Company ownership lifecycle.
The four roles
| Role | Level | What it can do |
|---|---|---|
owner | Highest | Everything: members, invitations, company configuration |
admin | High | The same as owner day to day |
member | Medium | Read and write company resources |
viewer | Low | Read only |
Where the role lives
The JWT issued at sign-in carries a role claim, but authorization does not trust that snapshot. On every request the authentication strategy re-resolves the user's current membership for the selected company and uses that membership's role. Consequences:
- Changing a member's role, removing the membership or deactivating the company takes effect on the next request, without waiting for the user to sign out.
- The token's
role/companyIdclaims are used to pick the company to resolve, not as the authorization source of truth. - The server still does not make a bare role lookup on every request: the resolution is part of the authentication step, so the cost is one membership read per request, not one per handler.
Changing a member's role
The role cannot be edited in place. The flow is:
- Remove the member from the company (
DELETE /v1/companies/:id/users/:userId). - Add them back with the new role (
POST /v1/companies/:id/users).
Who can do what
| Action | Owner | Admin | Member | Viewer |
|---|---|---|---|---|
| View companies and users | ✅ | ✅ | ✅ | ✅ |
| Create/edit companies | ✅ | ✅ | ❌ | ❌ |
| Delete companies | ✅ | ❌ | ❌ | ❌ |
Manage members (assigning member/viewer) | ✅ | ✅ | ❌ | ❌ |
Manage members (assigning owner/admin) | ✅ | ❌ | ❌ | ❌ |
| Create and revoke invitations | ✅ | ✅ | ❌ | ❌ |
| Change system configuration | ✅ | ✅ | ❌ | ❌ |
Hierarchy when assigning roles
An admin may add members, but only with the member or viewer role. Only an owner may grant owner or admin to another member (POST /v1/companies/:id/users) — otherwise an admin could promote themselves. See Companies → Add a member.
The same rule applies to invitations (POST /v1/companies/:id/invitations): an admin can only invite with member/viewer. It is revalidated again when the invitation is accepted (GET /v1/invitations/accept), using the creator's current role — in case they were demoted after creating it and before it was accepted. See Invitations.
Removing a member (DELETE /v1/companies/:id/users/:userId) follows the same hierarchy: an admin cannot remove an owner/admin, and nobody — not an owner, not a super admin — can leave the company without at least one owner (409). See Companies → Remove a member.
A platform super admin (isSuperAdmin === true) bypasses the role hierarchy (they can grant or remove OWNER/ADMIN in any company) but not the last-owner protection on removal. See Users → Super admin.
The first owner assignment does not go through this hierarchy
When someone creates a company (POST /v1/companies, or the registration with companyName — see Company ownership lifecycle), they become owner of that company automatically, without anyone "granting" it. The hierarchy on this page governs subsequent assignments to existing or new members, not the creator's initial membership.