# Organization invitations API

The organization invitations REST API lets authorized users list, retrieve, create, and revoke invitations for a Buildkite organization.

## Organization invitation data model



| `id` | UUID of the invitation. |
| --- | --- |
| `graphql_id` | The GraphQL ID of the invitation. Use this to look up the invitation using the [GraphQL API](/docs/apis/graphql-api). |
| `url` | The canonical API URL for this invitation. |
| `email` | The email address the invitation was sent to. |
| `state` | Current state of the invitation: `pending`, `accepted`, `revoked`, or `expired`. |
| `role` | The organization role offered: `admin` or `member`. |
| `sso_mode` | The SSO requirement for the invited member: `required` or `optional`. |
| `teams` | Array of team assignments included in the invitation. Each entry has an `id` (team UUID) and a `role` (`member` or `maintainer`). |
| `created_at` | ISO 8601 timestamp of when the invitation was created. |
| `created_by` | The user who created the invitation. |
| `accepted_at` | ISO 8601 timestamp of when the invitation was accepted, or `null`. |
| `accepted_by` | The user who accepted the invitation, or `null`. |
| `revoked_at` | ISO 8601 timestamp of when the invitation was revoked, or `null`. |
| `revoked_by` | The user who revoked the invitation, or `null`. |
| `expired_at` | ISO 8601 timestamp of when the invitation expired, or `null`. |



## List organization invitations

Returns a [paginated list](/docs/rest-api#pagination) of pending invitations for an organization, ordered from newest to oldest. The list does not include accepted, revoked, or expired invitations. You can retrieve those invitations individually by UUID.

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

```json
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "graphql_id": "T3JnYW5pemF0aW9uSW52aXRhdGlvbi0tLTAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDAwMQ==",
      "url": "https://api.buildkite.com/v2/organizations/acme-inc/invitations/00000000-0000-4000-8000-000000000001",
      "email": "new-member@example.com",
      "state": "pending",
      "role": "member",
      "sso_mode": "required",
      "teams": [],
      "created_at": "2024-11-12T09:15:04.000Z",
      "created_by": {
        "id": "00000000-0000-4000-8000-000000000002",
        "name": "Example User",
        "email": "example@example.com"
      },
      "accepted_at": null,
      "accepted_by": null,
      "revoked_at": null,
      "revoked_by": null,
      "expired_at": null
    }
  ],
  "links": {
    "self": "https://api.buildkite.com/v2/organizations/acme-inc/invitations?per_page=30",
    "next": "https://api.buildkite.com/v2/organizations/acme-inc/invitations?per_page=30&after=eyJjcmVhdGVkX2F0IjoiMjAyNC0xMS0xMlQwOToxNTowNC4wMDBaIn0="
  }
}
```

The response body contains the following pagination fields:

- `items`: The invitations on the current page.
- `links`: URLs for the current page and available `next` page. Follow these URLs instead of constructing cursors. The response also includes these links in the HTTP `Link` header.

Optional query string parameters:



| `after` | Returns the next page after the supplied cursor. Cannot be combined with `before`. |
| --- | --- |
| `before` | Returns the previous page before the supplied cursor. Cannot be combined with `after`. |
| `per_page` | Number of results per page. Defaults to `30` and has a maximum of `100`. |



Required scope: `read_organization_invitations`

Required permission: permission to invite organization members

Success response: `200 OK`

Error responses:



| `400 Bad Request` | The request supplies both cursor parameters, a non-string cursor value, or a `per_page` value outside the supported range. |
| --- | --- |
| `403 Forbidden` | The token does not have the required scope or the user does not have permission to invite organization members. |



## Get an organization invitation

Returns a single invitation by UUID. Unlike the list endpoint, this returns invitations in any state.

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

```json
{
  "id": "00000000-0000-4000-8000-000000000001",
  "graphql_id": "T3JnYW5pemF0aW9uSW52aXRhdGlvbi0tLTAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDAwMQ==",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/invitations/00000000-0000-4000-8000-000000000001",
  "email": "new-member@example.com",
  "state": "pending",
  "role": "member",
  "sso_mode": "required",
  "teams": [],
  "created_at": "2024-11-12T09:15:04.000Z",
  "created_by": {
    "id": "00000000-0000-4000-8000-000000000002",
    "name": "Example User",
    "email": "example@example.com"
  },
  "accepted_at": null,
  "accepted_by": null,
  "revoked_at": null,
  "revoked_by": null,
  "expired_at": null
}
```

Required scope: `read_organization_invitations`

Required permission: permission to invite organization members

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the required scope or the user does not have permission to invite organization members. |
| --- | --- |
| `404 Not Found` | The invitation UUID does not exist or belongs to a different organization. |



## Create organization invitations

Creates invitations for one or more email addresses. The response contains the created invitations. The API treats duplicate email addresses as one address, regardless of capitalization. The entire batch is validated before any invitations are created. If any address is invalid, no invitations are created.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/invitations" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["member@example.com", "admin@example.com"],
    "role": "member",
    "sso_mode": "required",
    "teams": [
      { "id": "00000000-0000-4000-8000-000000000003", "role": "member" }
    ]
  }'
```

```json
[
  {
    "id": "00000000-0000-4000-8000-000000000001",
    "graphql_id": "T3JnYW5pemF0aW9uSW52aXRhdGlvbi0tLTAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDAwMQ==",
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/invitations/00000000-0000-4000-8000-000000000001",
    "email": "member@example.com",
    "state": "pending",
    "role": "member",
    "sso_mode": "required",
    "teams": [
      { "id": "00000000-0000-4000-8000-000000000003", "role": "member" }
    ],
    "created_at": "2024-11-12T09:15:04.000Z",
    "created_by": {
      "id": "00000000-0000-4000-8000-000000000002",
      "name": "Example User",
      "email": "example@example.com"
    },
    "accepted_at": null,
    "accepted_by": null,
    "revoked_at": null,
    "revoked_by": null,
    "expired_at": null
  }
]
```

Required [request body properties](/docs/apis/rest-api#request-body-properties):



| `emails` | An array of email address strings to invite. |
| --- | --- |



Optional [request body properties](/docs/apis/rest-api#request-body-properties):



| `role` | The organization role to assign to the invitee: `admin` or `member`. Defaults to `member`. |
| --- | --- |
| `sso_mode` | The SSO requirement for the invitee: `required` or `optional`. When SSO is disabled for the organization, omitting this field defaults it to `required`. When SSO is enabled, this field is required, and omitting it returns `422 Unprocessable Entity`. |
| `teams` | An array of team assignment objects. Each object requires an `id` (team UUID) and a `role` (`member` or `maintainer`). Provide at most one assignment per team. Omit or provide an empty array to skip team assignments. |



Required scope: `write_organization_invitations`

Required permission: permission to invite organization members

Success response: `201 Created`

Error responses:



| `403 Forbidden` | The token does not have the required scope or the user does not have permission to invite organization members. |
| --- | --- |
| `422 Unprocessable Entity` | The request contains invalid input, such as a malformed email address, an invalid role or SSO mode, conflicting team assignments, an email address that is already a member, a batch size that exceeds the organization's invitation quota, or an organization user limit that has been reached. This response also occurs when the organization has SSO enabled and the request omits `sso_mode`. |



## Revoke an organization invitation

Revokes a pending invitation. Returns no content on success. Only pending invitations can be revoked.

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

Required scope: `write_organization_invitations`

Required permission: permission to invite organization members

Success response: `204 No Content`

Error responses:



| `403 Forbidden` | The token does not have the required scope or the user does not have permission to invite organization members. |
| --- | --- |
| `404 Not Found` | The invitation UUID does not exist or belongs to a different organization. |
| `422 Unprocessable Entity` | The invitation cannot be revoked because it has already been accepted, revoked, or expired. |