Skip to content

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 ​

RoleLevelWhat it can do
ownerHighestEverything: members, invitations, company configuration
adminHighThe same as owner day to day
memberMediumRead and write company resources
viewerLowRead 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/companyId claims 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:

  1. Remove the member from the company (DELETE /v1/companies/:id/users/:userId).
  2. Add them back with the new role (POST /v1/companies/:id/users).

Who can do what ​

ActionOwnerAdminMemberViewer
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.