Learn · Access control and auditability

Agent tokens

An agent token is what an agent presents to connect. Anyone holding one can start an agent against that cluster, join a queue, and be dispatched jobs intended for it.

Take a moment with that. Jobs carry your source, and often the environment a job’s queue is trusted with. A leaked agent token is not a read-only exposure — it is an invitation to receive work.

Controls worth applying

Expiry. Configure expiration dates on agent tokens. It bounds the window in which a leaked token is useful, and — more usefully day to day — it forces you to discover which automation is still using a token you thought was retired.

Scope by cluster. A token belongs to a cluster. Separate clusters mean a token leaked from a test environment does not register agents in the one holding production credentials.

Restrict the agent user. On self-hosted agents, apply granular command authorization so the buildkite-agent user can only perform the operations it actually needs. The agent process is the blast radius; make it small.

Watch the audit log for token use. Unexpected registration is one of the clearer signals available. A token being used from a new address is worth an alert.

The handover implication

This is where the partner track picks the topic up. When an implementation is handed to a customer’s team, agent tokens are among the credentials that change hands — and “who holds a token that can receive our jobs” is a question the customer needs a confident answer to long after you have gone.