---
title: "Managing API tokens"
description: "How to assign scoped tokens for using the CircleCI API"
doc_version: "unversioned"
last_updated: "2026-04-27"
---

> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# 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), and grant full read and write permissions.

**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](https://circleci.com/docs/guides/integration/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

1.  In the CircleCI application, go to your [User settings](https://app.circleci.com/settings/user).
    
2.  Select [Personal API Tokens](https://app.circleci.com/settings/user/tokens).
    
3.  Select **Create New Token** button.
    
4.  In the **Token name** field, type a memorable name for the token.
    
5.  Select **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.
    

> **Image:** screenshot showing where to find your personal API token settings

Figure 1. Personal API tokens available in user settings

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

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.  Select **Add API Token**.
    
4.  Choose a scope from the dropdown menu. These are described in the [Overview](#overview) section above.
    
5.  In the **Label** field, type a memorable label for the token.
    
6.  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

1.  In the CircleCI application, go to your [User settings](https://app.circleci.com/settings/user).
    
2.  Select [Personal API Tokens](https://app.circleci.com/settings/user/tokens).
    
3.  Select the **X** in the **Remove** column for the token you wish to replace and confirm your deletion.
    
4.  Select **Create New Token**.
    
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.  Select **Add API Token**.
    
7.  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

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.  Select 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.  Select **Create API Token**.
    
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.  Select **Add API Token**.
    

## Next steps

Some possible use cases for an API token might be:

*   [Embed Build Status Badges](https://circleci.com/docs/guides/integration/status-badges/) in your project’s README or other external page.
    
*   [Download Build Artifacts](https://circleci.com/docs/guides/optimize/artifacts/#downloading-all-artifacts-for-a-build-on-circleci) for safekeeping.
    
*   [Inject Environment Variables](https://circleci.com/docs/guides/security/inject-environment-variables-with-api/) into a build.