Agent tokens

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

Use scoped agent tokens to limit the Agent API actions agents can perform and the queues where they can register and explicitly acquire jobs.

Authenticate these requests with an API access token, using the read_clusters scope for reads or write_clusters for writes. With a personal API access token, your user must have the manage_cluster permission for the cluster. Creating a token also requires see_cluster_tokens. These management permissions are separate from the agent token's permissions array. A workload identity token needs access to the cluster instead. Learn more in Supported APIs and scopes.

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 string containing permitted CIDR-notation IPv4 addresses from which agents can use this token to connect to the cluster.
permissions An array of allowed Agent API actions. See the available permissions. An empty array grants no permission-controlled actions.
allow_all_queues Whether agents using the token can register and explicitly acquire jobs in any queue in the cluster.
allowed_queue_ids An array of queue UUIDs in the same cluster. With allow_all_queues: false, agents can register and explicitly acquire jobs only in these queues. An empty array with allow_all_queues: false denies all queues.
token The secret token value. Returned only when creating a token; omitted from list, get, and update responses.
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.
revoked_at The ISO8601 timestamp at which point the token was revoked. null for a token that hasn't been revoked.
agent_access_revoked_at The ISO8601 timestamp at which point agent access revocation was requested for the token. null if agent access hasn't been revoked.
agent_access_revocation_completed_at The ISO8601 timestamp at which point agent access revocation finished applying to every agent sourced from the token. null while revocation is still being processed.

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": "00000000-0000-4000-8000-000000000001",
    "graphql_id": "Q2x1c3RlclRva2VuLS0tMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMDAx",
    "description": "Windows agents",
    "allowed_ip_addresses": "192.0.2.0/24",
    "permissions": ["run_jobs", "code_repository_access", "write_build_metadata"],
    "allow_all_queues": false,
    "allowed_queue_ids": ["00000000-0000-4000-8000-000000000002"],
    "expires_at": "2030-01-01T00:00:00Z",
    "url": "https://api.buildkite.com/v2/organizations/example-org/clusters/00000000-0000-4000-8000-000000000003/tokens/00000000-0000-4000-8000-000000000001",
    "cluster_url": "https://api.buildkite.com/v2/organizations/example-org/clusters/00000000-0000-4000-8000-000000000003",
    "created_at": "2023-05-26T04:21:41.350Z",
    "created_by": {
      "id": "00000000-0000-4000-8000-000000000004",
      "graphql_id": "VXNlci0tLTAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDAwNA==",
      "name": "Sam Kim",
      "email": "sam@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/example",
      "created_at": "2013-08-29T10:10:03.000Z"
    }
  }
]

By default, revoked tokens are excluded from the list. Pass include_revoked=true to include them:

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

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": "00000000-0000-4000-8000-000000000001",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMDAx",
  "description": "Windows agents",
  "allowed_ip_addresses": "192.0.2.0/24",
  "permissions": ["run_jobs", "code_repository_access", "write_build_metadata"],
  "allow_all_queues": false,
  "allowed_queue_ids": ["00000000-0000-4000-8000-000000000002"],
  "expires_at": "2030-01-01T00:00:00Z",
  "url": "https://api.buildkite.com/v2/organizations/example-org/clusters/00000000-0000-4000-8000-000000000003/tokens/00000000-0000-4000-8000-000000000001",
  "cluster_url": "https://api.buildkite.com/v2/organizations/example-org/clusters/00000000-0000-4000-8000-000000000003",
  "created_at": "2023-05-26T04:21:41.350Z",
  "created_by": {
    "id": "00000000-0000-4000-8000-000000000004",
    "graphql_id": "VXNlci0tLTAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDAwNA==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  }
}

By default, a revoked token's ID returns 404 Not Found. Pass include_revoked=true to retrieve it:

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

Required scope: read_clusters

Success response: 200 OK

Create a token

This example allows agents to run jobs, access code repositories through the Agent API, and write build metadata on a selected queue. Replace the example queue UUID with one from your cluster's list of queues.

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": "2030-01-01T00:00:00Z",
    "allowed_ip_addresses": "192.0.2.0/24",
    "permissions": ["run_jobs", "code_repository_access", "write_build_metadata"],
    "allow_all_queues": false,
    "allowed_queue_ids": ["00000000-0000-4000-8000-000000000002"]
  }'
{
  "id": "00000000-0000-4000-8000-000000000001",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMDAx",
  "description": "Windows agents",
  "expires_at": "2030-01-01T00:00:00Z",
  "allowed_ip_addresses": "192.0.2.0/24",
  "permissions": ["run_jobs", "code_repository_access", "write_build_metadata"],
  "allow_all_queues": false,
  "allowed_queue_ids": ["00000000-0000-4000-8000-000000000002"],
  "url": "https://api.buildkite.com/v2/organizations/example-org/clusters/00000000-0000-4000-8000-000000000003/tokens/00000000-0000-4000-8000-000000000001",
  "cluster_url": "https://api.buildkite.com/v2/organizations/example-org/clusters/00000000-0000-4000-8000-000000000003",
  "created_at": "2023-05-26T04:21:41.350Z",
  "created_by": {
    "id": "00000000-0000-4000-8000-000000000004",
    "graphql_id": "VXNlci0tLTAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDAwNA==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  },
  "token": "YOUR_AGENT_TOKEN"
}

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. Cannot be changed after creation.
Example: 2030-01-01T00:00:00Z
allowed_ip_addresses A string of permitted CIDR-notation IPv4 addresses.
Example: "192.0.2.0/24"
permissions An array of permission strings. Omit to grant all current permissions. An explicit array grants only those permissions, with duplicates removed. An empty array grants no permission-controlled actions.
allow_all_queues A boolean that defaults to true. Set to false and supply allowed_queue_ids to restrict queue access.
allowed_queue_ids An array of queue UUIDs from the same cluster, with duplicates removed. Defaults to an empty array. Required when allow_all_queues is false; an empty array then denies all queues. Must be empty when allow_all_queues is true.

Unknown permission names, including the retired names read_pipelines and modify_steps, are rejected. A null or malformed permissions value is also rejected. Invalid permission or queue settings return 422 Unprocessable Entity without creating a token.

Required scope: write_clusters

Success response: 201 Created

Error responses:

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

Update a token

Supply permissions to replace the entire permission array. Omit permissions, allow_all_queues, or allowed_queue_ids to preserve the corresponding stored value. Supplying allowed_queue_ids replaces the queue array.

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",
    "allowed_ip_addresses": "192.0.2.0/24",
    "permissions": ["run_jobs", "code_repository_access", "write_build_metadata"],
    "allow_all_queues": false,
    "allowed_queue_ids": ["00000000-0000-4000-8000-000000000002"]
  }'
{
  "id": "00000000-0000-4000-8000-000000000001",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMDAx",
  "description": "Windows agents",
  "allowed_ip_addresses": "192.0.2.0/24",
  "permissions": ["run_jobs", "code_repository_access", "write_build_metadata"],
  "allow_all_queues": false,
  "allowed_queue_ids": ["00000000-0000-4000-8000-000000000002"],
  "expires_at": "2030-01-01T00:00:00Z",
  "url": "https://api.buildkite.com/v2/organizations/example-org/clusters/00000000-0000-4000-8000-000000000003/tokens/00000000-0000-4000-8000-000000000001",
  "cluster_url": "https://api.buildkite.com/v2/organizations/example-org/clusters/00000000-0000-4000-8000-000000000003",
  "created_at": "2023-05-26T04:21:41.350Z",
  "created_by": {
    "id": "00000000-0000-4000-8000-000000000004",
    "graphql_id": "VXNlci0tLTAwMDAwMDAwLTAwMDAtNDAwMC04MDAwLTAwMDAwMDAwMDAwNA==",
    "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"
allowed_ip_addresses A string of permitted CIDR-notation IPv4 addresses. Omit to preserve the restriction; set to null to clear it.
permissions The replacement array of permission strings, with duplicates removed. Omit to preserve the existing permissions; use an empty array to grant no permission-controlled actions.
allow_all_queues A boolean that controls whether agents can register and explicitly acquire jobs in any queue. Omit to preserve the stored value.
allowed_queue_ids The replacement array of queue UUIDs from the same cluster, with duplicates removed. Omit to preserve the existing queues. Must be empty when allow_all_queues is true.

To switch a restricted token to all queues, send "allow_all_queues": true and "allowed_queue_ids": [] together. Clearing the array while allow_all_queues is false denies all queues.

Saved permission changes take effect on subsequent requests from connected agents and running jobs, without re-registration. Queue changes apply to new registrations, including registrations using previously issued job acquisition tokens, and new stack batch JAT issuance.

Explicit job acquisition also checks current queue bindings. Removing queue access after registration can make the Agent API's /acquire endpoint return 404, including for a JAT-backed agent. Queue edits do not disconnect existing agents or cancel running jobs.

Invalid permission or queue settings return 422 Unprocessable Entity without changing the token. The same validation rules apply as when creating a token. The expiration date cannot be updated; supplying expires_at returns 400 Bad Request.

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" }

Revoke a token's agent access

Rejects the session and job credentials derived from the token, including credentials issued through job acquisition tokens. Use this to respond to a compromised token, rather than for routine rotation.

This revokes the token itself if it hasn't already been revoked. Calling this endpoint again after agent access has already been revoked for the token is safe, and returns the same result without creating duplicate audit log events.

curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens/{id}/agent-access-revocation"
{
  "id": "00000000-0000-4000-8000-000000000001",
  "revoked_at": "2026-11-17T04:21:41.350Z",
  "agent_access_revoked_at": "2026-11-17T04:21:41.350Z",
  "agent_access_revocation_completed_at": null
}

Revocation of existing agents' credentials is processed in the background in batches, so it can take a short time to complete. The agent_access_revocation_completed_at field remains null until every agent associated with the token has been processed. This action can't be undone.

Agents generally shut down shortly after their access is revoked, stopping any running jobs, but neither outcome is guaranteed. Some older agent versions may keep running without being able to accept new work. After revoking agent access, check directly in your infrastructure that affected agents and jobs have stopped, and stop any that remain running. Agents with revoked access can't report their status to Buildkite Pipelines, so the Buildkite interface may temporarily show them as connected even after they've stopped.

Revocation doesn't invalidate OIDC tokens already issued to jobs or external credentials already obtained using those tokens, such as cloud provider credentials. These remain usable until they expire or the external provider invalidates them. Revocation also doesn't affect other externally issued credentials, requests already authorized before it takes effect, or presigned storage URLs.

Required scope: write_clusters

Success response: 202 Accepted

Error responses:

503 Service Unavailable { "message": "Token revocation was saved, but agent access revocation couldn't be queued. Retry this operation." }