Agent tokens

A Buildkite agent running in a self-hosted architecture requires an agent token to connect to Buildkite and register for work. Agent tokens connect to Buildkite via a cluster, and can be accessed from the cluster's Agent Tokens page.

If you are managing agents in an unclustered environment, refer to unclustered tokens instead.

The initial agent token

When you create a new organization in Buildkite, an initial agent token is created (called Initial agent token within the Default cluster). This token can be used for testing and development and is only revealed once during the organization setup process. It's recommended that you create new, specific tokens for each new environment.

Using and storing tokens

An 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 agent tokens can be created by a cluster maintainer using the Agent Tokens page of a cluster, as well as the REST API's or GraphQL API's create agent token feature.

For these API requests, the cluster ID value submitted as part of the request is the target cluster the token is associated with.

An agent token's value is only displayed once

As soon as the agent token's value is displayed, copy its value and save it in a secure location.

If you forget to do this, you'll need to create a new token to obtain its value.

It is possible to create multiple agent tokens (for your Default cluster or any other cluster in your Buildkite organization) using the processes described in this section.

Using the Buildkite interface

To create an agent token for a cluster using the Buildkite interface:

  1. Select Agents in the global navigation to access the Clusters page.
  2. Select the cluster that will be associated with this agent token.
  3. Select Agent Tokens > New Token.

  4. In the Description field, enter an appropriate description for the agent token.

    Note: 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), as it is listed on the Agent Tokens page of your specific cluster the agent connects to. This page can be accessed by selecting Agents (in the global navigation) > the specific cluster > Agent Tokens.

  5. If you need to restrict which network addresses are allowed to use this agent token, enter these addresses (using CIDR notation) into the Allowed IP Addresses field.

    Note: Leave this field empty if there is no need to restrict the use of this agent token by network address. Learn more about this feature in Restrict an agent token's access by IP address.

  6. Select Create Token.

    Follow the instructions to copy and save your token to a secure location and click Okay, I'm done!. The new agent token appears on the cluster's Agent Tokens page.

Using the REST API

To create an agent token using the REST API, run the following example curl command:

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A description",
    "allowed_ip_addresses": "0.0.0.0/0"
  }'

where:

  • $TOKEN is an API access token scoped to the relevant Organization and REST API Scopes that your request needs access to in Buildkite.

  • {org.slug} can be obtained:

    • From the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite.

    • By running the List organizations REST API query to obtain this value from slug in the response. For example:

      curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations"

  • {cluster.id} can be obtained:

    • From the Cluster Settings page of your target cluster. To do this:
      1. Select Agents (in the global navigation) > the specific cluster > Settings.
      2. Once on the Cluster Settings page, copy the id parameter value from the GraphQL API Integration section, which is the {cluster.id} value.

    • By running the List clusters REST API query and obtain this value from the id in the response associated with the name of your target cluster (specified by the name value in the response). For example:

      curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"

  • description (required) should clearly identify the environment the token is intended to be used for (for example, Read-only token for static site generator), as it is listed on the Agent tokens page of your specific cluster the agent connects to. To access this page, select Agents (in the global navigation) > the specific cluster > Agent Tokens.

  • allowed_ip_addresses (optional) is/are the IP addresses which agents must be accessible through to access this agent token and be able to connect to Buildkite via your cluster. Use space-separated CIDR notation to enter IP addresses for this field value.

The new agent token appears on the cluster's Agent Tokens page.

Using the GraphQL API

To create an agent token using the GraphQL API, run the following example mutation:

mutation {
  clusterAgentTokenCreate(
    input: {
      organizationId: "organization-id"
      clusterId: "cluster-id"
      description: "A description"
      allowedIpAddresses: "0.0.0.0/0"
    }
  ) {
    clusterAgentToken {
      id
      uuid
      description
      allowedIpAddresses
      cluster {
        id
        uuid
        organization {
          id
          uuid
        }
      }
      createdBy {
        id
        uuid
        email
      }
    }
  }
}

where:

  • organizationId (required) can be obtained:

    • From the GraphQL API Integration section of your Organization Settings page, accessed by selecting Settings in the global navigation of your organization in Buildkite.

    • By running a getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, followed by a getOrgId query, to obtain the organization's id using the organization's slug. For example:

      Step 1. Run getCurrentUsersOrgs to obtain the organization slug values in the response for the current user's accessible organizations:

      query getCurrentUsersOrgs {
  viewer {
    organizations {
      edges {
        node {
          name
          slug
        }
      }
    }
  }
}

      Step 2. Run getOrgId with the appropriate slug value above to obtain this organization's id in the response:

      query getOrgId {
  organization(slug: "organization-slug") {
    id
    uuid
    slug
  }
}

      Note: The organization-slug value can also be obtained from the end of your Buildkite URL, by selecting Pipelines in the global navigation of your organization in Buildkite.

  • clusterId (required) can be obtained:

    • From the Cluster Settings page of your target cluster. To do this:
      1. Select Agents (in the global navigation) > the specific cluster > Settings.
      2. Once on the Cluster Settings page, copy the cluster parameter value from the GraphQL API Integration section, which is the cluster.id value.

    • By running the List clusters GraphQL API query and obtain this value from the id in the response associated with the name of your target cluster (specified by the name value in the response). For example:

      query getClusters {
  organization(slug: "organization-slug") {
    clusters(first: 10) {
      edges {
        node {
          id
          name
          uuid
          color
          description
        }
      }
    }
  }
}

  • description (required) should clearly identify the environment the token is intended to be used for (for example, Read-only token for static site generator), as it is listed on the Agent tokens page of your specific cluster the agent connects to. To access this page, select Agents (in the global navigation) > the specific cluster > Agent Tokens.

  • allowedIpAddresses (optional) is/are the IP addresses which agents must be accessible through to access this agent token and be able to connect to Buildkite via your cluster. Use space-separated CIDR notation to enter IP addresses for this field value.

The new agent token appears on the cluster's Agent Tokens page.

Update a token

Agent tokens can be updated by a cluster maintainer using the Agent Tokens page of a cluster, as well as the REST API's or GraphQL API's revoke agent token feature.

Only the Description and Allowed IP Addresses of an existing agent token can be updated.

For these API requests, the cluster ID value submitted as part of the request is the target cluster the token is associated with.

Using the Buildkite interface

To update a cluster's agent token using the Buildkite interface:

  1. Select Agents in the global navigation to access the Clusters page.
  2. Select the cluster containing the agent token to update.
  3. Select Agent Tokens and on this page, expand the agent token to update.

  4. Select Edit and update the following fields as required:

    • Description should clearly identify the environment the token is intended to be used for (for example, Read-only token for static site generator), as it is listed on the Agent tokens page of your specific cluster the agent connects to. This page can be accessed by selecting Agents (in the global navigation) > the specific cluster > Agent Tokens.

    • Allowed IP Addresses is/are the IP addresses which agents must be accessible through to access this agent token and be able to connect to Buildkite via your cluster. Use space-separated CIDR notation to enter IP addresses for this field value.

      Leave this field empty if there is no need to restrict the use of this agent token by network address. Learn more about this feature in Restrict an agent token's access by IP address.

  5. Select Save Token to save your changes.

    The agent token's updates will appear on the cluster's Agent Tokens page.

Using the REST API

To update an agent token using the REST API, run the following example curl command:

curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens/{id}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A description",
    "allowed_ip_addresses": "202.144.0.0/24 198.51.100.12"
  }'

where:

  • $TOKEN is an API access token scoped to the relevant Organization and REST API Scopes that your request needs access to in Buildkite.

  • {org.slug} can be obtained:

    • From the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite.

    • By running the List organizations REST API query to obtain this value from slug in the response. For example:

      curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations"

  • {cluster.id} can be obtained:

    • From the Cluster Settings page of your target cluster. To do this:
      1. Select Agents (in the global navigation) > the specific cluster > Settings.
      2. Once on the Cluster Settings page, copy the id parameter value from the GraphQL API Integration section, which is the {cluster.id} value.

    • By running the List clusters REST API query and obtain this value from the id in the response associated with the name of your target cluster (specified by the name value in the response). For example:

      curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"

  • {id} is that of the agent token, whose value can be obtained:

    • From the Buildkite URL path when editing the agent token. To do this:

      • Select Agents (in the global navigation) > the specific cluster > Agent Tokens > expand the agent token > Edit.
      • Copy the ID value between /tokens/ and /edit in the URL.

    • By running the List tokens REST API query and obtain this value from the id in the response associated with the description of your token (specified by the description value in the response). For example:

      curl -H "Authorization: Bearer $TOKEN" </span>
  - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens"

  • description (optional) should clearly identify the environment the token is intended to be used for (for example, Read-only token for static site generator), as it is listed on the Agent tokens page of your specific cluster the agent connects to. To access this page, select Agents (in the global navigation) > the specific cluster > Agent Tokens.

  • allowed_ip_addresses (optional) is/are the IP addresses which agents must be accessible through to access this agent token and be able to connect to Buildkite via your cluster. Use space-separated CIDR notation to enter IP addresses for this field value.

    This field can be omitted (where the default value is 0.0.0.0/0) if there is no need to restrict the use of this agent token by network address, or change the field's current value. Learn more about this feature in Restrict an agent token's access by IP address.

Using the GraphQL API

To update an agent token using the GraphQL API, run the following example mutation:

mutation {
  clusterAgentTokenUpdate(
    input: {
      organizationId: "organization-id"
      id: "token-id"
      description: "A description"
      allowedIpAddresses: "202.144.0.0/24 198.51.100.12"
    }
  ) {
    clusterAgentToken {
      id
      uuid
      description
      allowedIpAddresses
      cluster {
        id
        uuid
        organization {
          id
          uuid
        }
      }
      createdBy {
        id
        uuid
        email
      }
    }
  }
}

where:

  • organizationId (required) can be obtained:

    • From the GraphQL API Integration section of your Organization Settings page, accessed by selecting Settings in the global navigation of your organization in Buildkite.

    • By running a getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, followed by a getOrgId query, to obtain the organization's id using the organization's slug. For example:

      Step 1. Run getCurrentUsersOrgs to obtain the organization slug values in the response for the current user's accessible organizations:

      query getCurrentUsersOrgs {
  viewer {
    organizations {
      edges {
        node {
          name
          slug
        }
      }
    }
  }
}

      Step 2. Run getOrgId with the appropriate slug value above to obtain this organization's id in the response:

      query getOrgId {
  organization(slug: "organization-slug") {
    id
    uuid
    slug
  }
}

      Note: The organization-slug value can also be obtained from the end of your Buildkite URL, by selecting Pipelines in the global navigation of your organization in Buildkite.

  • id (required) is that of the agent token, whose value can only be obtained using the APIs, by running a getClustersAgentTokenIds query, to obtain the organization's clusters and each of their agent tokens' id values in the response. For example:

      query getClustersAgentTokenIds {
    organization(slug: "organization-slug") {
      clusters(first: 10) {
        edges {
          node {
            name
            id
            agentTokens(first: 10) {
              edges {
                node {
                  description
                  id
                }
              }
            }
          }
        }
      }
    }
  }

  • description (required) should clearly identify the environment the token is intended to be used for (for example, Read-only token for static site generator), as it is listed on the Agent tokens page of your specific cluster the agent connects to. To access this page, select Agents (in the global navigation) > the specific cluster > Agent Tokens.

    If you do not need to change the existing description value, specify the existing field value in the request.

  • allowedIpAddresses (optional) is/are the IP addresses which agents must be accessible through to access this agent token and be able to connect to Buildkite via your cluster. Use space-separated CIDR notation to enter IP addresses for this field value.

    This field can be omitted (where the default value is 0.0.0.0/0) if there is no need to restrict the use of this agent token by network address, or change the field's current value. Learn more about this feature in Restrict an agent token's access by IP address.

The agent token's updates will appear on the cluster's Agent Tokens page.

Revoke a token

Agent tokens can be revoked by a cluster maintainer using the Agent Tokens page of a cluster, as well as the REST API's or GraphQL API's revoke agent token feature.

For these API requests, the cluster ID value submitted as part of the request is the target cluster the token is associated with.

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.

Using the Buildkite interface

To revoke a cluster's agent token using the Buildkite interface:

  1. Select Agents in the global navigation to access the Clusters page.
  2. Select the cluster containing the agent token to revoke.
  3. Select Agent Tokens and on this page, expand the agent token to revoke.
  4. Select Revoke > Revoke Token in the confirmation message.

Using the REST API

To revoke an agent token using the REST API, run the following example curl command:

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens/{id}"

where:

  • $TOKEN is an API access token scoped to the relevant Organization and REST API Scopes that your request needs access to in Buildkite.

  • {org.slug} can be obtained:

    • From the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite.

    • By running the List organizations REST API query to obtain this value from slug in the response. For example:

      curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations"

  • {cluster.id} can be obtained:

    • From the Cluster Settings page of your target cluster. To do this:
      1. Select Agents (in the global navigation) > the specific cluster > Settings.
      2. Once on the Cluster Settings page, copy the id parameter value from the GraphQL API Integration section, which is the {cluster.id} value.

    • By running the List clusters REST API query and obtain this value from the id in the response associated with the name of your target cluster (specified by the name value in the response). For example:

      curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"

  • {id} is that of the agent token, whose value can be obtained:

    • From the Buildkite URL path when editing the agent token. To do this:

      • Select Agents (in the global navigation) > the specific cluster > Agent Tokens > expand the agent token > Edit.
      • Copy the ID value between /tokens/ and /edit in the URL.

    • By running the List tokens REST API query and obtain this value from the id in the response associated with the description of your token (specified by the description value in the response). For example:

      curl -H "Authorization: Bearer $TOKEN" </span>
  - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens"

Using the GraphQL API

To revoke an agent token using the GraphQL API, run the following example mutation:

mutation {
  clusterAgentTokenRevoke(
    input: {
      organizationId: "organization-id"
      id: "token-id"
    }
  ) {
    deletedClusterAgentTokenId
  }
}

where:

  • organizationId (required) can be obtained:

    • From the GraphQL API Integration section of your Organization Settings page, accessed by selecting Settings in the global navigation of your organization in Buildkite.

    • By running a getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, followed by a getOrgId query, to obtain the organization's id using the organization's slug. For example:

      Step 1. Run getCurrentUsersOrgs to obtain the organization slug values in the response for the current user's accessible organizations:

      query getCurrentUsersOrgs {
  viewer {
    organizations {
      edges {
        node {
          name
          slug
        }
      }
    }
  }
}

      Step 2. Run getOrgId with the appropriate slug value above to obtain this organization's id in the response:

      query getOrgId {
  organization(slug: "organization-slug") {
    id
    uuid
    slug
  }
}

      Note: The organization-slug value can also be obtained from the end of your Buildkite URL, by selecting Pipelines in the global navigation of your organization in Buildkite.

  • id (required) is that of the agent token, whose value can only be obtained using the APIs, by running a getClustersAgentTokenIds query, to obtain the organization's clusters and each of their agent tokens' id values in the response. For example:

      query getClustersAgentTokenIds {
    organization(slug: "organization-slug") {
      clusters(first: 10) {
        edges {
          node {
            name
            id
            agentTokens(first: 10) {
              edges {
                node {
                  description
                  id
                }
              }
            }
          }
        }
      }
    }
  }

Scope of access

An agent token is specific to the cluster it was associated when created (within a Buildkite organization), and can be used to register an agent with any queue defined in that cluster. Agent tokens can not be shared between different clusters within an organization, or between different organizations.

Session and job tokens

During registration, the agent exchanges its 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 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.

Token type Use Lifetime
Agent token Registering new agents. Forever unless manually revoked.
Session token Agent lifecycle APIs and starting jobs. Until the agent disconnects.
Job token Job APIs (including annotate, artifact, meta-data and pipeline commands). Until the job finishes.

Job tokens not supported in agents prior to v3.39.0

Agents prior to v3.39.0 use the session token for the BUILDKITE_AGENT_ACCESS_TOKEN environment variable and the job APIs.