Managing API access tokens

Token scopes

When an API access token is created, select the Buildkite organization it grants access to, and its scopes of access. GraphQL API access tokens cannot be restricted by scope.

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.

Token scopes are very granular, and for API access tokens, you can select some or all of the following scopes:

• Read Agents (read_agents): Permission to list and retrieve details of agents.
• Write Agents (write_agents): Permission to stop agents. To register agents, use an Agent token instead.
• Read Clusters (read_clusters): Permission to list and retrieve details of clusters.
• Write Clusters (write_clusters): Permission to create, update and delete clusters.
• Read Teams (read_teams): Permission to list teams.
• Write Teams (write_teams): Permission to create, update and delete teams.
• Read Artifacts (read_artifacts): Permission to retrieve build artifacts.
• Write Artifacts (write_artifacts): Permission to delete build artifacts.
• Read Builds (read_builds): Permission to list and retrieve details of builds.
• Write Builds (write_builds): Permission to create new builds.
• Read Job Environment Variables (read_job_env): Permission to retrieve job environment variables.
• Read Build Logs (read_build_logs): Permission to retrieve build logs.
• Write Build Logs (write_build_logs): Permission to delete build logs.
• Read Organizations (read_organizations): Permission to list and retrieve details of organizations.
• Read Pipelines (read_pipelines): Permission to list and retrieve details of pipelines.
• Write Pipelines (write_pipelines): Permission to create, update and delete pipelines.
• Read Pipeline Templates (read_pipeline_templates): Permission to list and retrieve details of pipeline templates.
• Write Pipeline Templates (write_pipeline_templates): Permission to create, update and delete pipeline templates.
• Read Rules (read_rules): Permission to list and retrieve details of rules.
• Write Rules (write_rules): Permission to create or delete rules.
• Read User (read_user): Permission to retrieve basic details of the user.
• Read Suites (read_suites): Permission to list and retrieve details of test suites; including runs, tests, executions, etc.
• Write Suites (write_suites): Permission to create, update and delete test suites.
• Read Test Plan (read_test_plan): Permission to retrieve test plan information.
• Write Test Plan (write_test_plan): Permission to create test plan.
• Read Portals (read_portals): Permission to list and retrieve details of portals.
• Write Portals (write_portals): Permission to create, update, and delete portals.
• Read Registries (read_registries): Permission to list and retrieve details of registries.
• Write Registries (write_registries): Permission to create and update registries.
• Delete Registries (delete_registries): Permission to delete registries.
• Read Packages (read_packages): Permission to list and retrieve details of packages.
• Write Packages (write_packages): Permission to create packages.
• Delete Packages (delete_packages): Permission to delete packages.

When creating API access tokens, you can also restrict which network address are allowed to use them, using CIDR notation.

Auditing tokens

Viewing the API Access Audit page requires Buildkite organization administrator privileges. The page can be found in the Audit section of the Buildkite organization's Settings in the global navigation.

All tokens that currently have access to your organization's data will be listed. The table includes the scope 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.

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

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. You can search for tokens using usernames, token scopes, full IP addresses, admin privileges, or the value of the token itself.

From the API Access Audit page, navigate through to the token you'd like to remove, 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

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.

GitHub secret scanning program

Learn more about this program in Token security.

FAQs

Can I view an existing token?

No, you can change the scope and description of a token, or revoke it, but you can't view the actual token after creating it

Can I re-add my organization to a token?

No. If an organization has revoked a token, it cannot be re-added to the token. The token owner would have to create a new token with access to your organization.

Can I delete a token?

Yes. If you need to delete a token entirely, you can use the REST API access-token endpoint. You will need to know the full token value.

If you own the token, you can revoke your token from the API access token page in your Personal Settings.

What happens if I remove the access for a token that's currently in use?

The token will lose access to the organization data. Any future API requests will no longer successfully authorize.