Managing API Tokens

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


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

  1. Personal: These tokens are used to interact with the CircleCI API 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. Useful for embedding status badges.
    • Read Only tokens grant read only access to the project’s API.
    • Admin tokens grant read and write access for the project’s API.

Note: API tokens cannot be modifed after they have been created. The only way to change existing tokens is to delete and recreate them.

Creating a personal API token

  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.

Creating a project API token

  1. In the CircleCI application, go to your project’s settings by clicking the gear icon next to your project.
  2. In the Permissions section, click on API Permissions.
  3. Click the Create Token button.
  4. Choose a scope from the dropdown menu.
  5. In the Token Label field, type a memorable label for the token.
  6. Click the Add Token button.

To delete a project API token, click the X in the Remove column. When the confirmation window appears, click the Remove button.

Next steps

API tokens are not useful unless you do something with them. Here are a few ideas: