Organization members API

The organization members API endpoint allows users to view and manage members of a Buildkite organization. Member paths use the user's UUID, which is returned as the member's id.

Organization member data model

`id`	UUID of the user
`name`	Name of the user
`email`	Email of the user
`role`	The user's role within the organization: `admin` or `member`
`sso_mode`	The member's SSO requirement: `required` or `optional`. Only returned for organization admins or when viewing your own membership.

List organization members

Returns a list of an organization's members.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/members"

[
  {
    "id": "0185c636-fcbf-4a6c-b49d-c4048e7b8aea",
    "name": "Scout Finch",
    "email": "scout@example.com",
    "role": "admin",
    "sso_mode": "required"
  },
  {
    "id": "0185dbbf-8447-4f72-ac7e-4ea3c2ec8381",
    "name": "Huck Finn",
    "email": "huck@example.com",
    "role": "member",
    "sso_mode": "required"
  }
]

Required scope: read_organizations

Required permission: permission to view teams in the organization

Success response: 200 OK

Get an organization member

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/members/{user.uuid}"

{
  "id": "0185dbbf-8447-4f72-ac7e-4ea3c2ec8381",
  "name": "Victor Frankenstein",
  "email": "vic@example.com",
  "role": "member",
  "sso_mode": "required"
}

Required scope: read_organizations

Required permission: permission to view teams in the organization

Success response: 200 OK

Update an organization member

Updates a member's role or SSO mode within the organization. At least one of role or sso_mode must be provided. You cannot update your own membership.

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/members/{user.uuid}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "sso_mode": "optional"
  }'

{
  "id": "0185dbbf-8447-4f72-ac7e-4ea3c2ec8381",
  "name": "Victor Frankenstein",
  "email": "vic@example.com",
  "role": "admin",
  "sso_mode": "optional"
}

Optional request body properties:

`role`	The role to assign to the member: `admin` or `member`
`sso_mode`	The SSO requirement for the member: `required` or `optional`

Required scope: write_organizations

Required permission: permission to update the organization member

Success response: 200 OK

Error responses:

`403 Forbidden`	The token does not have the required scope, the user cannot update the member, or the user attempts to update their own membership.
`404 Not Found`	The organization or member could not be found or accessed.
`422 Unprocessable Entity`	The request does not provide `role` or `sso_mode`, supplies an unsupported value, or the member cannot be updated.

Remove an organization member

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/members/{user.uuid}"

Required scope: write_organizations

Required permission: permission to remove the organization member

Success response: 204 No Content

Error responses:

`403 Forbidden`	The token does not have the required scope or the user cannot remove the member.
`404 Not Found`	The organization or member could not be found or accessed.
`422 Unprocessable Entity`	The member cannot be removed, such as when removing them would leave the organization without an administrator.