urlscan.io logo urlscan.io
SecurityTrails logo

circleci.com Open in urlscan Pro
13.32.121.103  Public Scan

Back to summary
Submitted URL: https://go.circleci.com/NDg1LVpNSC02MjYAAAGJHr5jQrZbD6XzRR95IWxBnp8SviubIqVLGHD2zl7He6bnLye0bV-Exs9jSW8lmxXwTh_A5GY=
Effective URL: https://circleci.com/docs/managing-api-tokens/?mkt_tok=NDg1LVpNSC02MjYAAAGJHr5jQlHheVImQ4OLJ9BNHzrvb62XlK1CF0ob6sDtTK...
Submission: On January 05 via manual from US — Scanned from DE

Form analysis 1 forms found in the DOM

<form novalidate="" action="" role="search" class="css-cssveg">
  <div class="css-409epr">
    <div size="24" color="currentColor" class="css-19wtgi5"><svg role="img" focusable="false" viewBox="0 0 24 24" aria-label="Search" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="css-bleycz">
        <path fill-rule="evenodd" clip-rule="evenodd"
          d="M14 9C14 11.7614 11.7614 14 9 14C6.23858 14 4 11.7614 4 9C4 6.23858 6.23858 4 9 4C11.7614 4 14 6.23858 14 9ZM13.1922 14.6064C12.0236 15.4816 10.5723 16 9 16C5.13401 16 2 12.866 2 9C2 5.13401 5.13401 2 9 2C12.866 2 16 5.13401 16 9C16 10.5723 15.4816 12.0236 14.6064 13.1922L21.7019 20.2877C22.0924 20.6782 22.0924 21.3114 21.7019 21.7019C21.3114 22.0924 20.6782 22.0924 20.2877 21.7019L13.1922 14.6064Z">
        </path>
      </svg></div>
  </div>
  <div data-testid="search-documentation-reset" class="css-xxqz7m">
    <div size="28" color="currentColor" class="css-1pgy7j"><svg role="img" focusable="false" viewBox="0 0 24 24" aria-label="Cancel" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="css-bleycz">
        <path
          d="M17.9865 7.45711C18.3771 7.06658 18.3771 6.43342 17.9865 6.04289C17.596 5.65237 16.9628 5.65237 16.5723 6.04289L12.0294 10.5858L7.48653 6.04289C7.096 5.65237 6.46284 5.65237 6.07231 6.04289C5.68179 6.43342 5.68179 7.06658 6.07231 7.45711L10.6152 12L6.07231 16.5429C5.68179 16.9334 5.68179 17.5666 6.07231 17.9571C6.46284 18.3476 7.096 18.3476 7.48653 17.9571L12.0294 13.4142L16.5723 17.9571C16.9628 18.3476 17.596 18.3476 17.9865 17.9571C18.377 17.5666 18.377 16.9334 17.9865 16.5429L13.4436 12L17.9865 7.45711Z">
        </path>
      </svg></div>
  </div><input type="text" placeholder="Search" data-testid="search-documentation-inputbox" value="" class="css-2ls5mi">
</form>

Text Content

Docs

Start Building for Free

HomeDocsOrbsImages
CircleCI.comAcademyBlogCommunitySupport


 * Getting started
   
 * Pipelines
   
 * Execution environments
   
 * Configuration
   
 * Package and re-use config with orbs
   
 * Insights
   
 * Security and permissions
   
 * Projects
   
 * Developer toolkit
   
 * Examples and guides
   
 * Deployment
   
 * Reference
   
 * Server administration v4.x
   
 * Server administration v3.x
   
 * Server administration v2.x
   
 * CircleCI plans
   
 * Contributing to CircleCI docs
   


MANAGING API TOKENS

3 months ago2 min read
Last updated • Read time
Cloud
This document is applicable to CircleCI Cloud
Server v4.x
This document is applicable to CircleCI Server v4.x
Server v3.x
This document is applicable to CircleCI Server v3.x
Server v2.x
This document is applicable to CircleCI Server v2.x

ON THIS PAGE

 * Overview
 * Creating a personal API token
 * Creating a project API token
 * Rotating Personal and Project API Tokens
 * Rotating a Personal API Token
 * Rotating a Project API Token
 * Next steps

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

There are two types of API token 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 modified after they have been created. The only way
to change existing tokens is to delete and recreate them, also known as “token
rotation”.


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 and confirm
your deletion in the dialog window.


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


ROTATING PERSONAL AND PROJECT 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.
 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.

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


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 a build’s artifacts for safekeeping.
 * Inject environment variables into a build.

--------------------------------------------------------------------------------


HELP MAKE THIS DOCUMENT BETTER

This guide, as well as the rest of our docs, are open source and available on
GitHub. We welcome your contributions.

 * Suggest an edit to this page (please read the contributing guidefirst).
 * To report a problem in the documentation, or to submit feedback and comments,
   please open an issue on GitHub.
 * CircleCI is always seeking ways to improve your experience with our platform.
   If you would like to share feedback, please join our research community.


NEED SUPPORT?

Our support engineers are available to help with service issues, billing, or
account related questions, and can help troubleshoot build configurations.
Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums,
and training resources.

--------------------------------------------------------------------------------

CircleCI Documentation by CircleCI is licensed under a Creative Commons
Attribution-NonCommercial-ShareAlike 4.0 International License.

Docs
CircleCI RSS feedCircleCI FacebookCircleCI TwitterCircleCI GitHubCircleCI
TwitchCircleCI LinkedIn
 * Terms of Use
 * Privacy Policy
 * Cookie Policy
 * Security

© 2023 Circle Internet Services, Inc., All Rights Reserved.