Team and roles
People get access to your organization by invitation. What they can do once inside is decided by their role, and what they can see is bounded by the workspaces they can reach.
The built-in roles
Three roles exist out of the box.
| Role | For |
|---|---|
| Admin | Full access, including settings, billing configuration and managing other people |
| Member | Day-to-day work: reading customers, subscriptions and invoices without changing how the platform is configured |
| No access | An account that exists but can do nothing. Useful for suspending somebody without deleting them |
A role is a bundle of permissions. GET /v1/roles returns each role with the
permissions it grants, and GET /v1/permissions lists every permission. Both
come from the same source the API enforces, so they are the reference to trust.
This page does not copy that list: a copy would drift, and a wrong permission
table is worse than none.
Roles are organization-wide
A role is not per workspace. Someone who is an admin is an admin everywhere in your organization, including sandbox.
What is bounded per workspace is the data: two permissions govern workspaces, one to see them and one to create, rename or delete them. Somebody without the first sees only the workspace they are in.
Sandbox is not a safety boundary for people
Because roles are organization-wide, giving somebody access so they can "just try things in sandbox" gives them the same role in live. If that is not what you want, the answer is a narrower role, not a different workspace.
Over the API
Invitations, members and roles all have public endpoints:
| Call | Does |
|---|---|
GET /v1/invitations, POST /v1/invitations, DELETE /v1/invitations/{id} | Invite people and withdraw a pending invitation |
GET /v1/members | List members with their email, status and role names |
PATCH /v1/members/{id}/roles | Add roles (assign) and take roles away (unassign) in one call |
PATCH /v1/members/{id}/status | Suspend ("suspended") or restore ("active") a member |
DELETE /v1/members/{id} | Remove a member: drops every role, ends the membership and their sessions |
/v1/roles | Read and manage roles |
{id} is the member's user_id. Roles are named as they are listed, for example
admin, member and no_access.
Make a member an admin
None of these can leave the organization without an administrator: suspending,
removing or taking the admin role from the last admin answers
409 LAST_ADMIN_GUARD.
People and machines
A role is for a person. An API key is for a system, carries its own scopes, and should be narrower than any human role you would grant.
Do not share a person's credentials with a service. When somebody leaves you disable their account; you should not also have to work out which integrations stop.
Reference
| Topic | When you need it |
|---|---|
| API keys | Access for systems rather than people |
| Workspaces | The boundary a role operates within |
| Security | Two-factor and session policy |
| Organization settings | Where members and invitations live |