Give agents only the access they need

Buildkite has released two opt-in security controls for agent tokens: token permissions and queue scopes. Agents connecting with restricted tokens can only use the capabilities those tokens allow, such as uploading steps or reading secrets. Scoped agent tokens let your platform team give different parts of your infrastructure only the permissions they need.

Decide what each token can do

An agent that runs tests doesn't always need to upload more pipeline steps, read secrets, or request OIDC tokens. You can now grant those capabilities independently. For example, give your build agents permission to run jobs and upload artifacts, and use a separate token for agents that upload dynamic pipelines. Jobs inherit the permissions of the agent token used to register their agent. Running a job no longer has to mean having access to every Agent API capability.

Requests without a required permission return 403 Forbidden, with an error naming the missing permission.

Choose where agents can accept jobs

You might separate work into queues based on its security requirements: signing artifacts on tightly controlled infrastructure, for example, and routine tests on general-purpose workers. Previously, a cluster's agent tokens allowed registration to any self-hosted queue in that cluster. You can now scope a token to specific queues, so agents using it can only register with those queues.

A token for your test queue can register agents there, but registration attempts for release or deploy are denied. Or leave All queues selected to allow existing and future queues in the cluster.

Queue scopes and token permissions are separate controls. To register an agent in a queue, its token must grant Run jobs and allow access to that queue. Queue scopes also apply when an agent explicitly acquires a job. Changing a token's queue access doesn't disconnect existing agents or stop running jobs.

Attempting to register with a queue outside the token's scope returns 401 Unauthorized. The agent isn't registered.

Give monitoring its own credential

A tool that reads queue metrics doesn't need permission to run jobs or operate a stack. Give it a token with only Read metrics, and keep job execution and stack-controller access on separate credentials.

Get started

Open your cluster's Agent Tokens page and create or edit a token. Choose its Queue access, then expand Permissions to select the capabilities it needs. You can also manage both through the REST and GraphQL APIs.

Both controls are opt-in. Existing tokens retain their permissions and queue access. New tokens default to full permissions and all queues unless you restrict them.

Have questions or need help? Reach out to us at support@buildkite.com.