Supported APIs and scopes

Workload identity federation supports a subset of the REST API for Buildkite Pipelines and organization access. Use the API references below for endpoint paths, request parameters, and responses. This page lists the supported scopes and workload identity limitations.

Support for additional resources is coming soon.

Supported APIs

A token needs both the operation's scope and access to its pipeline through the workload identity's Resource Access setting. Listing operations return only accessible resources. Requests for individual resources outside that access return 404 Not Found, even for public pipelines.

API reference Supported scopes Workload identity limitations
API reference Pipelines API Supported scopes read_pipelines, write_pipelines Workload identity limitations Can't create pipelines, even with All pipeline access.
API reference Pipeline schedules API Supported scopes read_pipelines Workload identity limitations Read-only. Can't create, update, or delete schedules.
API reference Pipeline triggers API Supported scopes read_pipelines, write_pipelines Workload identity limitations Can read, update, and delete existing triggers, but can't create triggers.
API reference Pipeline trigger deliveries API Supported scopes read_pipelines Workload identity limitations Read-only.
API reference Builds API Supported scopes read_builds, write_builds, retry_builds Workload identity limitations Can't rebuild merge queue builds. Retry operations accept either write_builds or retry_builds.
API reference Jobs API Supported scopes read_builds, write_builds, retry_builds, read_job_env Workload identity limitations Can't unblock jobs restricted to specific teams or reprioritize jobs in clusters that restrict job priority changes. Job retries accept either write_builds or retry_builds.
API reference Job logs Supported scopes read_build_logs Workload identity limitations Read-only. Can't delete job logs.
API reference Hosted agent sessions Supported scopes write_builds Workload identity limitations SSH and remote desktop sessions require session access to be enabled for the organization and an eligible job.
API reference Annotations API Supported scopes read_builds, write_builds Workload identity limitations Can read, create, and delete build and job annotations in accessible pipelines.
API reference Step uploads API Supported scopes read_builds Workload identity limitations Read-only.
API reference Artifacts API Supported scopes read_artifacts Workload identity limitations Can list, get, and download artifacts, but can't delete them.
API reference Organizations API, Organization usage API, and Rate limits Supported scopes read_organizations Workload identity limitations Own organization only. Not restricted by pipeline access.
API reference Organization members API Supported scopes read_organizations, write_organizations Workload identity limitations Own organization only. Can read members, update roles and SSO mode, and remove members. Listing and getting members require teams to be enabled. The organization must retain at least one administrator.
API reference Access token API Supported scopes No additional scope Workload identity limitations Can inspect or revoke the token used for the request.

Organization scopes grant organization-wide access regardless of Resource Access. Grant them only when the workload needs that access.

Choose the required scopes in Grantable Scopes, then select a subset in Default Scopes or request a subset during token exchange. See Create a workload identity.

Unsupported APIs and scopes

GraphQL, Buildkite Test Engine, and Buildkite Package Registries aren't supported. Neither are agent and cluster management, teams, secrets, pipeline templates, rules, organization settings, or workload identity management. Their scopes aren't available to workload identities.

The write_build_logs and write_artifacts scopes can be configured on a workload identity, but don't currently enable log or artifact deletion. An available scope doesn't guarantee access to every operation that accepts it.