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.
Overview
In CircleCI you can create personal and project API tokens:
- Personal API tokens
-
These tokens are used to interact with the CircleCI APIs (v1 and v2). Tokens created manually through the web app grant full read and write permissions. Manually-created tokens expire on a date you set when you create them. An expired token stops working, so you must replace it with a new token. Tokens created through the OAuth 2.0 Dynamic Client Registration flow are scoped to the access level (Read, Write, or Admin) chosen by the user during authorization.
- Project API tokens
-
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).
-
| 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". |
Create a personal API token
-
In the CircleCI application, go to your User settings.
-
Select Personal API Tokens.
-
Select Create New Token button.
-
In the Token name field, type a memorable name for the token.
-
Set an expiry date for the token. You must choose a date no more than one year in the future.
-
Select Add API Token button.
-
After the token appears, copy and paste it to another location. You will not be able to view the token again.
CircleCI emails you before a personal API token expires. For details, see the Personal API Token Expiry Notifications section.
To delete a personal API token, click the X in the Remove column and confirm your deletion in the dialog window.
Create a project API token
-
In the CircleCI web app, select your org from the org cards on your user homepage.
-
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
-
Select the ellipsis
next to your project and select Project Settings.You can also access project settings from each project overview page using the Settings button. -
Select API Permissions.
-
Select Add API Token.
-
Choose a scope from the dropdown menu. These are described in the Overview section above.
-
In the Label field, type a memorable label for the token.
-
Select 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.
Rotate API tokens
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.
Rotating a personal API token
-
In the CircleCI application, go to your User settings.
-
Select Personal API Tokens.
-
Select the X in the Remove column for the token you wish to replace and confirm your deletion.
-
Select Create New Token.
-
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.
-
Set an expiry date for the token.
-
Select Add API Token.
-
After the token appears, copy and paste it to another location. You will not be able to view the token again.
Rotating a project API token
-
In the CircleCI web app, select your org from the org cards on your user homepage.
-
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
-
Select the ellipsis
next to your project and select Project Settings.You can also access project settings from each project overview page using the Settings button. -
Select API Permissions.
-
Select the X in the Remove column for the token you wish to replace. When the confirmation window appears, enter the text
DELETEin the form and click the Delete API Token button. -
Select Create API Token.
-
Choose the same scope used for the old token from the dropdown menu.
-
In the Label field, type a label for the token. It can be the same name given to the old token.
-
Select Add API Token.
Personal API token expiry notifications
CircleCI emails you when a personal API token is approaching its expiry date. You receive an email 30 days, 15 days, seven days, and one day before the token expires.
| Expiry notifications are mandatory communications, so you cannot opt out of them. To stop the emails for a token you no longer need, delete the token as described in the Rotating a Personal API Token section. |
Next steps
Some possible use cases for an API token might be:
-
Embed Build Status Badges in your project’s README or other external page.
-
Download Build Artifacts for safekeeping.
-
Inject Environment Variables into a build.