Members and roles
Just want to do it in the dashboard? See the guide: Invite a colleague and give them a role or Create a role with only the rights it needs.
An organization has members. Each member holds one role. The role decides what they can see and change.
Built-in roles
Section titled “Built-in roles”| Role | For | Can |
|---|---|---|
owner | The person accountable for the org | Every permission. An org always keeps at least one owner |
admin | People who run the org day to day | Members, roles, teams, invitations, API keys, SSO, SCIM, spend cap, audit log, notifications, the product’s settings |
member | People who use the product | Read and work with the product’s data. See members, roles and teams |
viewer | People who need the summary | See the org, its usage and the product’s summaries. No detailed data |
auditor | Compliance reviews and SIEM exports | Read everything, including the audit log. Change nothing |
pipeline | A CI job or an agent | Run the product’s automated workflow. API keys only, never a person |
owner and admin hold the same permissions today. The difference is ownership: an owner cannot be demoted or removed while they are the org’s only owner.
Organization → Access → Roles lists every role and the permissions it grants. GET /v1/orgs/{org_id}/roles returns the same list.
Custom roles
Section titled “Custom roles”A custom role is a named set of permissions, for a need the built-in roles do not fit. Create one in Organization → Access → Roles or with POST /v1/orgs/{org_id}/roles.
- You can only grant permissions you hold yourself.
- A change applies to each holder on their next request.
- A custom role can be deleted only when no member, active API key, open invitation or SCIM group mapping uses it.
Add a member
Section titled “Add a member”Two ways, both need the admin role:
| Way | When | Where |
|---|---|---|
| Invitation link | The person has no account yet, or you don’t know if they do | Organization → Access → Invitations, or POST /v1/orgs/{org_id}/invites |
| Add directly | The person already has an account | Organization → Access → Members, or POST /v1/orgs/{org_id}/members with their email |
An invitation link without an email is reusable: anyone who holds it can join. Add email to address it to one person. Only that account can accept it, and they see it in their account without needing the link. Revoke a link in Invitations when you no longer need it.
With SSO or SCIM, the identity provider can create memberships for you. See SSO & SCIM.
Change or remove a member
Section titled “Change or remove a member”In Organization → Access → Members, use the row’s actions. Through the API:
PATCH /v1/orgs/{org_id}/members/{user_id}changes the role, or setsis_active: falseto block the member in this org only. Their other orgs are not affected.DELETE /v1/orgs/{org_id}/members/{user_id}removes the member.
Both refuse to act on your own membership, and refuse to demote, block or remove the org’s only owner.
Group members into teams in Organization → Access → Teams. Teams decide who reviews which repository. See Review routing.
Ownership
Section titled “Ownership”The person who creates an organization is its owner.
When the only owner leaves the org or deletes their account, they decide first what happens to it:
- Hand it over — name an active member. That member becomes the owner.
- Lock it — the org keeps its data. Every call to it answers
423until a platform admin unlocks or deletes it.
The dashboard asks for this choice. Through the API, send it in the body:
curl -X POST http://localhost:8000/v1/orgs/$ORG_ID/leave \ -H "Cookie: mcp_session=..." -H "Content-Type: application/json" \ -d "{\"hand_over\": {\"$ORG_ID\": \"$NEW_OWNER_USER_ID\"}}"Without a choice, the request is refused with 409 and the list of orgs that need one.
Leave an organization
Section titled “Leave an organization”Any member can leave: Account → Organizations → Leave, or POST /v1/orgs/{org_id}/leave. This needs a signed-in session, not an API key.
If SCIM or SSO created your membership, the identity provider re-creates it on its next sync. Ask for your removal there instead.
Delete an organization
Section titled “Delete an organization”Members cannot delete an organization. A platform admin schedules the deletion in Platform Admin. The org is locked at once and removed after a grace period. See Deleting an organization.
Before that, an admin can download all of the org’s data: Audit log → Export organization data, or GET /v1/orgs/{org_id}/export.