Agent tokens

An agent token is used to connect agents to a Buildkite cluster.

Token data model

id The ID of the agent token.
graphql_id The GraphQL ID of the token.
description The description of the token.
allowed_ip_addresses A list of permitted CIDR-notation IPv4 addresses that agents must be accessible through, to access this token and connect to your Buildkite cluster.
url The canonical API URL of the token.
cluster_url The API URL of the Buildkite cluster that the token belongs to.
created_at The date and time when the token was created.
created_by The user who created the token.
expires_at The ISO8601 timestamp at which point the token expires and prevents agents configured with this token from re-connecting to their Buildkite cluster.

List tokens

Returns a paginated list of a cluster's agent tokens.

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

[
  {
    "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
    "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
    "description": "Windows agents",
    "allowed_ip_addresses": "202.144.0.0/24",
    "expires_at" : "2026-01-01T00:00:00Z",
    "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
    "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
    "created_at": "2023-05-26T04:21:41.350Z",
    "created_by": {
      "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
      "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
      "name": "Sam Kim",
      "email": "sam@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/example",
      "created_at": "2013-08-29T10:10:03.000Z"
    }
  }
]

Required scope: read_clusters

Success response: 200 OK

Get a token

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

{
  "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
  "description": "Windows agents",
  "allowed_ip_addresses": "202.144.0.0/24",
  "expires_at" : "2026-01-01T00:00:00Z",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
  "created_at": "2023-05-26T04:21:41.350Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  }
}

Required scope: read_clusters

Success response: 200 OK

Create a token

Token visibility

To ensure the security of tokens, the value is only included in the response for the request to create the token. Subsequent responses do not contain the token value.

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": "Windows agents", "expires_at": "2025-01-01T00:00:00Z", "allowed_ip_addresses": "202.144.0.0/24" }'

{
  "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
  "description": "Windows agents",
  "expires_at": "2025-01-01T00:00:00Z",
  "allowed_ip_addresses": "202.144.0.0/24",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
  "created_at": "2023-05-26T04:21:41.350Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  },
  "token": "igo6HEj5fxQbgBTDoDzNaZzT"
}

Required request body properties:

description Description for the token.
Example: "Windows agents"

Optional request body properties:

expires_at The ISO8601 timestamp at which point the token expires and prevents agents configured with this token from re-connecting to their Buildkite cluster.
Example: 2025-01-01T00:00:00Z

Required scope: write_clusters

Success response: 201 Created

Error responses:

422 Unprocessable Entity { "message": "Validation failed: Reason for failure" }

Update a token

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": "Windows agents", "expires_at": "2025-01-01T00:00:00Z", "allowed_ip_addresses": "202.144.0.0/24" }'

{
  "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
  "description": "Windows agents",
  "allowed_ip_addresses": "202.144.0.0/24",
  "expires_at" : "2026-01-01T00:00:00Z",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
  "created_at": "2023-05-26T04:21:41.350Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  }
}

Request body properties:

description Description for the token.
Example: "Windows agents"

Required scope: write_clusters

Success response: 200 OK

Error responses:

422 Unprocessable Entity { "message": "Validation failed: Reason for failure" }

Revoke a token

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

Required scope: write_clusters

Success response: 204 No Content

Error responses:

422 Unprocessable Entity { "message": "Reason the token couldn't be revoked" }