Unclustered agent tokens

The default token

Your Buildkite organization's unclustered agent tokens page, accessible through Agents (from the global navigation) > Unclustered > Agent Tokens, may have the Default agent registration token, which is the original default token when your organization was created. If you had previously saved this token's value in a safe place, this token can be used for testing and development. However, it's recommended that you create new, specific tokens for each new environment.

Using and storing tokens

An unclustered agent token is used by the Buildkite agent's start command, and can be provided on the command line, set in the configuration file, or provided using the environment variable BUILDKITE_AGENT_TOKEN.

It's recommended you use your platform's secret storage (such as the AWS Systems Manager Parameter Store) to allow for easier rollover and management of your agent tokens.

Create a token

New unclustered agent tokens can be created using the GraphQL API with the agentTokenCreate mutation.

For example:

mutation {
  agentTokenCreate(input: {
    organizationID: "organization-id",
    description: "A description"
  }) {
    tokenValue
    agentTokenEdge {
      node {
        id
      }
    }
  }
}

You can find your organization-id in your Buildkite organization settings page, or by running the following GrapqQL query:

query GetOrgID {
  organization(slug: "organization-slug") {
    id
  }
}

The token description should clearly identify the environment the token is intended to be used for (for example, Read-only token for static site generator), and is listed on the Agent tokens page of the Agents (from the global navigation) > Unclustered area.

It is possible to create multiple unclustered agent tokens using the GraphQL API.

Revoke a token

Unclustered agent tokens can be revoked using the GraphQL API query with the agentTokenRevoke mutation.

You need to pass your unclustered agent token as the ID in the mutation.

First, you can retrieve a list of agent token IDs using this query:

query GetAgentTokenID {
  organization(slug: "organization-slug") {
    agentTokens(first:50) {
      edges {
        node {
          id
          uuid
          description
        }
      }
    }
  }
}

Then, using the token ID, revoke the unclustered agent token:

mutation {
  agentTokenRevoke(input: {
    id: "token-id",
    reason: "A reason"
  }) {
    agentToken {
      description
      revokedAt
      revokedReason
    }
  }
}

Once a token is revoked, no new agents will be able to start with that token. Revoking a token does not affect any connected agents.

Scope of access

Unclustered agent tokens are specific to each Buildkite organization (created before February 26, 2024), and can be used to register an agent with any unclustered queue. Unclustered agent tokens can not be shared between organizations.

Additional agent tokens

In addition to the initial unclustered agent token, the Buildkite Agent automatically generates and manages two internal types of tokens during its operation. These tokens are session tokens and job tokens.

Session tokens

Session tokens are internal tokens that last for the lifetime of the agent connection. They are used by the agent to request and start new jobs, and remain valid until the agent disconnects from Buildkite.

Job tokens

Job tokens are internal agent access tokens that are generated for each individual job when it starts. They are exposed to the job as the environment variable BUILDKITE_AGENT_ACCESS_TOKEN and are used by the Buildkite Agent's local Job API, which provides access to various CLI commands (including annotate, artifact, meta-data, and pipeline commands). Job tokens are scoped to a single job for security reasons, limiting both the duration and the scope of access, and are valid until the job finishes.

You can set a default or maximum command timeout to further scope the lifetime of job tokens.

Token exchange process

When an agent starts, it follows the token exchange process:

1. The agent connects to the Buildkite Agent API to register itself using its configured agent token (BUILDKITE_AGENT_TOKEN).
2. The Agent API generates and returns a session token to the agent.
3. The agent uses this session token to poll for available jobs and manage its connection to Buildkite.
4. When the agent accepts a job, Buildkite generates a job token specific to that job.