How do you scope Buildkite API and agent tokens to least privilege?

Buildkite has three credential types worth scoping: API access tokens tied to a user, agent tokens tied to a cluster, and OAuth tokens issued to the CLI. Give each the narrowest scopes, an expiry, and an IP allowlist where the docs allow, and keep agent tokens away from the jobs themselves.

Which Buildkite tokens exist?

Buildkite's documentation separates them clearly.

API access tokens are issued to individual user accounts, not to organizations. They call the REST and GraphQL APIs.

Agent tokens are long-lived credentials a self-hosted agent uses to connect and register for work. They belong to a cluster.

OAuth tokens are what the Buildkite CLI gets when you run bk auth login.

Different tokens, different blast radius, so the controls differ.

How do you scope an API access token?

When you create one, Buildkite asks for a description, an organization, an expiry, REST scopes and optionally a list of allowed IP addresses in CIDR notation. Use all of them.

REST scopes are granular per feature, with read, write and delete permissions. Scopes exist for pipelines, builds, build logs, artifacts, agents, clusters and more. A token that only needs to trigger builds should hold write_builds and little else.

Two items deserve attention. The GraphQL scope is described as a full-access option with no further granularity, so avoid it unless you need it, or restrict GraphQL use through portals. And read_job_env returns job environment variables, which can include sensitive values, so grant it rarely.

Because tokens belong to users, they inherit the person's life cycle. Organization administrators can review them on the API Access Audit page. Put that page on a quarterly calendar and remove tokens whose owners left or whose purpose ended.

What about CLI tokens?

Buildkite documents that bk auth login requests all available REST scopes by default, though the server limits it to what your account can do, and the GraphQL scope is excluded. For least privilege, pass --scopes. For example, request only the read group, or read plus write_builds. Document that flag in your onboarding notes.

How do you protect agent tokens?

Agent tokens are long-lived, and revoking one does not affect already connected agents, per Buildkite. So treat a leak as two steps: revoke the token, then stop or replace the running agents.

Practical rules:

• One token per cluster purpose, not one shared token for everything. Buildkite creates an initial agent token for testing and development, shown once; replace it with purpose-named tokens.
• Only organization administrators or cluster maintainers should manage them.
• For stack-managed ephemeral agents, Buildkite recommends a short-lived job acquisition token as the registration credential, which keeps the agent token in the stack controller and out of job workloads.
• Never bake an agent token into an image that jobs can read.

How does this connect to pipeline signing?

Scoped tokens limit what an attacker can call. Signed pipelines limit what an agent will run. They address different failures, so use both. See our note on signing and provenance for Buildkite.

What to do

1. List every API access token on the audit page and delete what you cannot explain.
2. Recreate long-lived tokens with an expiry, the smallest REST scopes and an IP allowlist.
3. Avoid the GraphQL scope and read_job_env unless required.
4. Use bk auth login --scopes with minimal scopes.
5. Replace the initial agent token with named, per-cluster tokens.
6. Prefer short-lived job acquisition tokens for ephemeral agents.
7. Write a leak runbook: revoke, then stop connected agents.

Quick check

Sources

• Managing API access tokens, Buildkite Docs, fetched 18 October 2026
• Agent tokens, Buildkite Docs, fetched 18 October 2026

Last reviewed: 18 October 2026.