Managing API access tokens

Buildkite API access tokens are issued to individual Buildkite user accounts, not Buildkite organizations.

Creating and editing API access tokens

You can create and edit API access tokens through your Personal Settings.

You'll need to be a member of a Buildkite organization to generate and use an API access token with this organization. This is especially important for contributors to public and open-source projects.

Once API access tokens have been created within a Buildkite organization, Buildkite organization administrators can use the API Access Audit page to view and manage all such tokens that have been created within it.

Create an API access token

To create a new API access token:

Select Personal Settings in the global navigation > API Access Tokens to open its page.
Select New API Access Token.

If prompted, enter your password in the Confirm Password field.
Enter an appropriate Description for your new API access token, and ensure Token is selected in Credential Type.
Ensure the appropriate Buildkite organization is selected in Organization Access. This organization is the one that your API access token will have access to and operate within.

Note: Your most recently used Buildkite organization is automatically selected from this list.
Select an appropriate Token Expiry duration.
Select from the appropriate REST API Scopes or GraphQL API permission, or both. Learn more about these in Token scopes.
To restrict which network addresses your new API access token can operate from, specify these addresses in the Allowed IP Addresses field, using CIDR notation.
Select Create New API Access Token to create the token, and enter your password again if prompted.

Note: On the resulting page, don't forget to copy your new API access token's value now, as this is the last time you'll see this value.

Edit an existing API access token

To edit an existing API access token:

Select Personal Settings in the global navigation > API Access Tokens to open its page.
Select the API access token to edit from the list of existing ones on this page.
Edit the required fields as you would when you created the API access token, as well as its token scopes.
Select Update API Access Token to save your changes.

Token scopes

When an API access token is being created or edited, define the required REST API Scopes, for which you select permissions (READ, WRITE, DELETE) for different Buildkite platform features that this token is granted access to. Each individual combination of these permissions and features is known as a scope.

You can also select Enable GraphQL API access as an additional scope, noting that this is a full-access option that does not provide any further granular scopes/permission restrictions to Buildkite platform features. To restrict an API access token's scope to individual GraphQL API features, you can do so by implementing GraphQL API portals.

A token's REST API Scopes are organized by Buildkite platform feature categories and their individual features. See the relevant tables within this section for details of these features, along with the permission types (READ, WRITE, DELETE) that each of these features provide.

For REST API scopes, you can use the following:

The Search feature allows you to filter the available Buildkite platform features.
The Presets feature allows you to select between all Read only, all Read + Write, or all Full Access (which includes DELETE) permissions across all of these Buildkite platform features, regardless of whether or not these features have been filtered using Search.

Token scopes are also available to OAuth access tokens, which are issued by the Buildkite platform on behalf of your Buildkite user account for certain processes. However, when these processes occur, while you can select a Buildkite organization you're a member of, which the OAuth token grants access to, the Buildkite platform defines the scopes for these access tokens.

A token's REST API scopes are granular, and you can select some or all of the following Buildkite platform features and their scopes.

CI/CD

Feature and scopes	Description	Read	Write
Pipelines `read_pipelines`, `write_pipelines`	List and retrieve details of pipelines—create, update, and delete pipelines.	✅	✅
Builds `read_builds`, `write_builds`	List and retrieve details of builds—create new builds.	✅	✅
Build Logs `read_build_logs`, `write_build_logs`	Retrieve build logs—delete build logs.	✅	✅
Job Environment `read_job_env`	Retrieve job environment variables.	✅
Artifacts `read_artifacts`, `write_artifacts`	Retrieve build artifacts—delete build artifacts.	✅	✅
Agents `read_agents`, `write_agents`	List and retrieve details of agents—stop agents. To register self-hosted agents, use an agent token instead.	✅	✅
Clusters `read_clusters`, `write_clusters`	List and retrieve details of clusters—create, update, and delete clusters.	✅	✅
Pipeline Templates `read_pipeline_templates`, `write_pipeline_templates`	List and retrieve details of pipeline templates—create, update, and delete pipeline templates.	✅	✅
Rules `read_rules`, `write_rules`	List and retrieve details of rules—create or delete rules.	✅	✅

Organization and users

Feature and scopes	Description	Read	Write
Organizations `read_organizations`	List and retrieve details of organizations.	✅
Teams `read_teams`, `write_teams`	List teams—create, update, and delete teams.	✅	✅
User `read_user`	Retrieve basic details of the user.	✅

Security

Feature and scopes	Description	Read	Write	Delete
Secrets `read_secrets_details`, `write_secrets`	List and retrieve details about secrets—create, update, and delete secrets.	✅	✅

Test Engine

Feature and scopes	Description	Read	Write	Delete
Suites `read_suites`, `write_suites`	Retrieve suite information—create suites.	✅	✅
Test Plan `read_test_plan`, `write_test_plan`	Retrieve test plan information—create test plan.	✅	✅

Packages

Feature and scopes	Description	Read	Write	Delete
Registries `read_registries`, `write_registries`, `delete_registries`	List and retrieve details of registries—create and update registries; delete registries.	✅	✅	✅
Packages `read_packages`, `write_packages`, `delete_packages`	List and retrieve details of packages—create packages, delete packages.	✅	✅	✅

Portals

Feature and scopes	Description	Read	Write	Delete
Portals `read_portals`, `write_portals`	List and retrieve details of portals—create, update, and delete portals.	✅	✅

Auditing tokens

Viewing the API Access Audit page requires Buildkite organization administrator privileges. You can access this page by selecting Settings in the global navigation > API Access Audit within the Audit section.

All API access tokens that users within your Buildkite organization have created, and currently have access to your organization's data will be listed. The table includes the scopes of each token, how long ago they were created, and how long since they've been used.

From the API Access Audit page, navigate through to any token to see more detailed information about its scopes and the most recent request, where you can also remove a token's access to your Buildkite organization's data if required.

Screenshot of the API Access Audit page displaying a list of all tokens

The list of tokens can be filtered by username, scopes, IP address, or whether the user has admin privileges.

Screenshot of the API Access Audit page displaying a filtered list of tokens that have the GraphQL scope

Removing an organization from a token

If you have old API access tokens that should no longer be used, or need to prevent such a token from performing further actions, Buildkite organization administrators can remove the token's access to organization data.

From the API Access Audit page, find the API token whose access you want to remove and select it. You can search for tokens using usernames, token scopes, full IP addresses, admin privileges, or the value of the token itself.

Screenshot of the API access token page with the Revoke Access button at the bottom of the screen

Scroll to the end of the specific token's page, then select Remove Organization from Token.

Removing access from a token sends a notification email to the token's owner, who cannot re-add your organization to the token's scope.

Limiting API access by IP address

If you'd like to limit an API token's access to your organization by IP address, you can create an allowlist of IP addresses in the organization's API security settings.

You can also manage the allowlist with the organizationApiIpAllowlistUpdate mutation in the GraphQL API.

Inactive API tokens revocation

Enterprise plan feature

Revoking inactive API tokens automatically is only available on an Enterprise plan.

To enable the inactive API access tokens revocation feature, navigate to your organization's security settings and specify the maximum timeframe for inactive tokens to remain valid.

An inactive API access token refers to one that has not been used within the specified duration. When an API token surpasses the configured setting, Buildkite will automatically revoke the token's access to your organization.

Upon token revocation, Buildkite will notify the owner of their change in access.

Programmatically managing tokens

The access-token REST API endpoint can be used to retrieve or revoke an API access token. See the REST API access token page for further information.

API token lifecycle

Buildkite's API access tokens have the following lifecycle characteristics:

API access tokens are issued for users within a Buildkite organization. The tokens are stored in the Buildkite database (linked to the user ID) and by the user for which they're issued.
The tokens are associated with a specific user and can only be revoked by that user. Buildkite organization administrators can remove a user from an organization, which prevents the user from accessing any organization resources and pipelines, and prevents access using any API access token associated with that user.

API token security

This section explains risk mitigation strategies which you can implement, and others which are in place, to prevent your Buildkite API access tokens being compromised.

Rotation

Buildkite's API access tokens have no built-in expiration date. The best practices regarding regular credential rotation recommended by OWASP suggest rotating the tokens at least once a year. In case of a security compromise or breach, it is strongly recommended that the old tokens are invalidated or inactive ones revoked, and new tokens are issued.

The API Access Tokens page has a Duplicate button that can be used to create a new token with the same permissions as the existing token.