Skip to content

API tokens#

Codacy provides account and repository-level API tokens that allow you to:

The sections below provide details about the two types of API tokens and instructions on how to generate and revoke them.

Warning

Never write API tokens to your configuration files and keep your API tokens well protected, as they grant owner permissions to your projects on Codacy.

It's a best practice to store API tokens as environment variables. Check the documentation of your CI/CD platform on how to do this.

Generating and revoking account API tokens#

Account API tokens are defined at the Codacy user account level. Each account API token authorizes access to the same organizations, repositories, and operations as the roles and permissions of the owner of the account.

Important

If you're using an account API token to upload coverage be sure to check the roles that your Git provider account must have to authorize uploading coverage to Codacy.

Use a dedicated service account to integrate Codacy with your repositories. This prevents disruption of service if the user who created an account API token loses access to the repositories, which may happen when a user leaves the team or the organization.

You can create new account API tokens programmatically using the Codacy API or using the Codacy UI:

  1. Open your account, tab Access management.

  2. Click the button Create API token under Account API tokens.

  3. Select an expiration date from the modal options. You can select 7, 30, or 90 days, or set a custom date up to a maximum of one year from creation.

    Creating an account API token modal

Tip

You can create multiple account API tokens. This can be useful to have a more flexible control by revoking only a specific token.

When you have tokens created, you can view them inside the tokens table. By hovering a token, you are able to copy its value.

The account API tokens table

To delete an account API token, click the trash icon in the Actions column of the table. After this, all applications or services using that token to access the Codacy API will fail to authenticate and will receive the reply {"error":"not found"}.

Account API tokens created before expiration dates became mandatory still work, and appear in the table with the expiration set as Never. Codacy recommends replacing them:

  1. Create a new account API token with an expiration date.
  2. Update every application or service that authenticates with the old token.
  3. Delete the token without an expiration date.

Creating the replacement first prevents the applications still using the old token from failing to authenticate.

Generating and revoking repository API tokens#

Repository API tokens are defined on individual repositories. Each repository API token only authorizes access to the corresponding repository — it can't be used to access any other repository or organization data. On API v3, it's further restricted to the operations listed below; on the legacy API v2, a repository API token has full access to that repository's endpoints, with no such restriction.

You can create new repository API tokens programmatically using the Codacy API or using the Codacy UI:

  1. Open your repository Settings, tab API tokens.

  2. Click the button Create API token under Repository API tokens.

    • Optionally give the token a name. Names may contain only letters, numbers, and dashes, up to 100 characters, and must be unique within the repository. If you don't set a name, Codacy generates one for you.
    • Select an expiration date for the token. Repository API tokens must always have an expiration date, up to a maximum of one year from creation — there's no option to create a token that never expires.

    Tip

    You can create multiple (up to 100) API tokens per repository. This can be useful to have a more flexible control by revoking only a specific token.

    Creating a repository API token

    Selecting Custom date lets you pick any date up to one year from today:

    Setting a custom expiration date for a repository API token

Codacy displays the value of the new token only once, immediately after you create it. Copy it and store it somewhere safe before leaving the page — you won't be able to see it again. From then on, the tokens table shows only the name, expiration, and creation date of each token.

A newly created repository API token, with its value displayed once

Note

Repository API tokens created before expiration dates became mandatory still work, and appear in the table with the expiration set as Never. Codacy recommends replacing them:

  1. Create a new repository API token with an expiration date.
  2. Update every application or service that authenticates with the old token, such as your CI pipelines.
  3. Delete the old tokens, individually or all at once using the delete all tokens without expiration shortcut in the banner.

Repository API tokens without an expiration date

When a repository API token expires, requests authenticated with it are rejected with a distinct "token expired" error, so you can tell an expired token apart from one that's invalid or was deleted.

To revoke a repository API token, click the trash icon in the Actions column of the table. To revoke several tokens at once, select them using the checkboxes and click Delete tokens:

Selecting multiple repository API tokens to delete them

After this, all applications or services using those tokens to access the Codacy API will fail to authenticate and will receive the reply {"error":"not found"}.

What repository API tokens can do on API v3#

On API v3, a repository API token authorizes only the following operations, and only on the repository it was created for. This restriction doesn't apply to API v2, where a repository API token can access any endpoint for its repository:

For any other endpoint, including creating, listing, or revoking API tokens themselves, use an account API token instead.

See also#

Was this page helpful?

Your feedback helps us improve the documentation.

Edit this page on GitHub Contact support