Managing API Access Tokens

On the API Access Audit page, organization admins can view all tokens that have been created with access to their organization data. As well as auditing user tokens and what access they have, you can also remove a token's access to your organization data if required.

Token scopes

When you create a token, select the organizations it grants access to, and the scope of the access.

REST API scopes are very granular, you can select some or all of the following:

  • Read Agents read_agents - Permission to list and retrieve details of agents
  • Modify Agents write_agents - Permission to create, update and delete agents
  • Read Teams read_teams - Permission to list 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
  • Modify 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 User read_user - Permission to retrieve basic details of the user

GraphQL tokens cannot be limited by scope.

Auditing tokens

Viewing the API Access Audit page requires admin privileges. The page can be found in the Security section of the Organization Settings sidebar.

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.

Click through any token to see more detailed information about its scopes and the most recent request.

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

The list of tokens can be filtered by username, token value, 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 tokens that should no longer be used, or need to prevent a token from performing further actions, administrators can remove the token's access to organization data.

From the API access audit page, find the 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.

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

Click through the token you'd like to remove, then click the 'Remove Organization from Token' button.

Removing access from a token will send a notification email to the token's owner.

Removing access from a token does not delete the token. Token owners can re-add your organization to their token's scope.

Programatically 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.

FAQs

Can I re-add my organization to a token?

Yes, the token owner can re-add the organization to the token from their API Access Tokens settings page.

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.