Skip to content
DashboardWebsite

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.

RoleForCan
ownerThe person accountable for the orgEvery permission. An org always keeps at least one owner
adminPeople who run the org day to dayMembers, roles, teams, invitations, API keys, SSO, SCIM, spend cap, audit log, notifications, the product’s settings
memberPeople who use the productRead and work with the product’s data. See members, roles and teams
viewerPeople who need the summarySee the org, its usage and the product’s summaries. No detailed data
auditorCompliance reviews and SIEM exportsRead everything, including the audit log. Change nothing
pipelineA CI job or an agentRun 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.

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.

Two ways, both need the admin role:

WayWhenWhere
Invitation linkThe person has no account yet, or you don’t know if they doOrganization → Access → Invitations, or POST /v1/orgs/{org_id}/invites
Add directlyThe person already has an accountOrganization → 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.

In Organization → Access → Members, use the row’s actions. Through the API:

  • PATCH /v1/orgs/{org_id}/members/{user_id} changes the role, or sets is_active: false to 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.

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 423 until a platform admin unlocks or deletes it.

The dashboard asks for this choice. Through the API, send it in the body:

Terminal window
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.

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.

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.