Managing API Tokens

To use the CircleCI API or view details about your pipelines, you will need API tokens with the appropriate permissions. This document describes the types of API tokens available, as well as how to create and delete them.

There are two types of API token you can create within CircleCI.

1. Personal: These tokens are used to interact with the CircleCI APIs (v1 and v2), and grant full read and write permissions.
2. Project: These tokens allow you to read/write information for specific projects. Project tokens have three scope options: Status, Read Only, and Admin. - Status tokens grant read access to the project’s build statuses. Used for embedding status badges. - Read Only tokens grant read only access to the project’s API (v1 only). - Admin tokens grant read and write access for the project’s API (v1 only).

Note: API tokens cannot be modified after they have been created. The only way to change existing tokens is to delete and recreate them, also known as “token rotation”.

1. In the CircleCI application, go to your User settings.
2. Click Personal API Tokens.
3. Click the Create New Token button.
4. In the Token name field, type a memorable name for the token.
5. Click the Add API Token button.
6. After the token appears, copy and paste it to another location. You will not be able to view the token again.

To delete a personal API token, click the X in the Remove column and confirm your deletion in the dialog window.

1. In the CircleCI application, go to your project’s settings. There are various ways to get there. One way is to select Projects in the sidebar, then the ellipsis (...) next to your project and select Project Settings.
2. Select API Permissions.
3. Click the Add API Token button.
4. Choose a scope from the dropdown menu. These are described in the Overview section above.
5. In the Label field, type a memorable label for the token.
6. Click the Add API Token button.

To delete a project API token, Click the X in the Remove column for the token you wish to replace. When the confirmation window appears, enter the text DELETE in the form and click the Delete API Token button.

API Token rotation occurs when an old API token is replaced with a new token.

Because API Tokens can be shared, passed around between employees and teams, and exposed inadvertently, it is always good practice to periodically regenerate new API Tokens. Many organizations automate this process, running a script when an employee leaves the company or when a token has been considered leaked.

1. In the CircleCI application, go to your User settings.
2. Click Personal API Tokens.
3. Click the X in the Remove column for the token you wish to replace and confirm your deletion.
4. Click the Create New Token button.
5. In the Token name field, type a new name for the old token you are rotating. It can be the same name given to the old token.
6. Click the Add API Token button.
7. After the token appears, copy and paste it to another location. You will not be able to view the token again.

1. In the CircleCI application, go to your project’s settings. There are various ways to get there. One way is to select Projects in the sidebar, then the ellipsis (...) next to your project and select Project Settings.
2. Select API Permissions.
3. Click the X in the Remove column for the token you wish to replace. When the confirmation window appears, enter the text DELETE in the form and click the Delete API Token button.
4. Click the Create API Token button.
5. Choose the same scope used for the old token from the dropdown menu.
6. In the Label field, type a label for the token. It can be the same name given to the old token.
7. Click the Add API Token button.

Some possible use cases for an API token might be:

• Embed Build Status Badges in your project’s README or other external page.
• Download a build’s artifacts for safekeeping.
• Inject environment variables into a build.