> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Buildkite

*This article covers both Buildkite connectors. The standard connector is read-only. The **Buildkite (Multi-Auth)** connector adds provisioning.*

<Note>
  The Buildkite (Multi-Auth) connector is in Early Access. Contact your Lumos team to have it enabled for your domain.
</Note>

## After this article

You will be able to connect Buildkite to Lumos to sync organization members, their roles, and teams for visibility and Access Reviews, and, with the Buildkite (Multi-Auth) connector, to invite and remove organization members and manage their team memberships from Lumos.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes (Multi-Auth only) | Organization member accounts. Lumos can invite (create) and remove members |
| Roles | Permission | Yes | No | Roles in Buildkite |
| Groups | Permission | Yes | Yes (Multi-Auth only) | Buildkite teams. Lumos can add and remove team members |

**Provisioning behavior:**

* **Create:** Lumos sends an organization invitation over the REST API, so the token does not need GraphQL access.
* **Idempotent writes:** inviting a member who is already in the organization, adding a team membership that already exists, or removing one that is already gone is reported as already matching instead of failing.

## Required plan and roles

* **Buildkite role:** the API token must be created by a user who is a member of the organization you want to sync. The Organization Slug is read from **Settings → Organization Settings**.
* **Authentication:** a Buildkite **Personal Access Token (PAT)**.
* **Token scopes:**
  * `read_organizations`: read organization details and members
  * `read_teams`: read teams and team memberships
* **Permission scoping:** the standard connector is read-only. The Buildkite (Multi-Auth) connector can also invite and remove members and change team memberships when the token carries the write scopes.

## Read-only access vs provisioning

**Is read-only possible?** Yes. The standard connector only syncs members, roles, and teams. The Buildkite (Multi-Auth) connector can provision; create its token with only the two read scopes to keep it read-only.

**What read-only requires.** A member of the organization creates the PAT in Buildkite under Personal Settings, API Access Tokens, selecting both read scopes and the single organization to connect. Follow the steps below to generate the token and find the Organization Slug.

**What full provisioning requires.** The Buildkite (Multi-Auth) connector with an API token carrying `read_organizations`, `read_teams`, and the write scopes for organization invitations and team membership, created by a member of the organization. Enter the **Organization Slug** when connecting.

**Watch out for.** A Buildkite PAT is tied to the single organization selected at token creation, connect additional organizations with separate tokens and integration cards. If data is missing, confirm the token has both `read_organizations` and `read_teams` scopes.

## Instructions

**Phase 1: Generate an API Access Token in Buildkite**

1. Log in to Buildkite and click your profile picture → **Personal Settings** → **API Access Tokens**.
2. Click **New API Access Token** and enter your password.
3. Fill in the description and pick the organization to connect. Lumos connects to only the selected organization tied to this token.
4. Select the scopes `read_organizations` and `read_teams`.
5. Click **Create New API Access Token** and copy the token.
6. Get your Organization Slug: select your organization and navigate to **Settings** → **Organization Settings**, then copy the **Slug** field.

**Phase 2: Connect in Lumos**

1. Click the Buildkite card in your Lumos integrations (reconnect an existing card or add a new one).
2. Enter the **API Token** and **Organization Slug**.
3. Click **Connect**.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Connection fails or data is missing.** Confirm the token has both `read_organizations` and `read_teams` scopes and that the Organization Slug exactly matches the **Slug** field in **Settings → Organization Settings**.

**Only one organization syncs.** This is expected. A Buildkite PAT is tied to the single organization selected at token creation. Connect additional organizations with separate tokens and integration cards.