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.

Session and job tokens

During registration, the unclustered agent exchanges its unclustered agent token for a session token. The session token lasts for the lifetime of the agent and is used to request and start new jobs. When each job is started, the unclustered agent gets a job token specific to that job. The job token is exposed to the job as the environment variable BUILDKITE_AGENT_ACCESS_TOKEN, and is used by various CLI commands (including the annotate, artifact, meta-data, and pipeline commands).

Job tokens are valid until the job finishes. To ensure job tokens have a limited lifetime, you can set a default or maximum command timeout.