Agent Tokens

The Buildkite Agent requires an agent token to connect to Buildkite and register for work. If you are an admin of your Buildkite organization, you can view the tokens on your Agents page.

The default token

When you create a new organization in Buildkite, a default agent token is created. This token can be used for testing and development, but it's recommended to create new, specific tokens for each new environment.

Using and storing tokens

The 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 via 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.

Creating tokens

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

For example:

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

The token description should clearly identify the environment the token is intended to be used for, and is shown on your Agents page.

Revoking tokens

Tokens can be revoked using the GraphQL API with the agentTokenRevoke mutation.

For example:

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

Agent tokens are specific to each Buildkite organization, and can be used to register an agent with any queue. Agent tokens can not be shared between organizations.

Session tokens

During registration, the agent exchanges the agent token for a session token. The session token is exposed to the job as the environment variable BUILDKITE_AGENT_ACCESS_TOKEN, and is used by the annotate, artifact, meta-data and pipeline commands. Session tokens are scoped to a specific agent, and are valid for the duration the agent is connected.