Creating project API tokens programmatically#

To create new project API tokens for your Codacy repositories programmatically, use the Codacy API endpoint createRepositoryApiToken. You can also list all project API tokens for a repository using the endpoint listRepositoryApiTokens.

For example, if you're setting up coverage for all your repositories and prefer not to use a single account API token that grants the same permissions as an administrator, you need to create an individual project API token for each repository.

Example: Creating a project API token for a single repository#

This example creates a new project API token for a repository and outputs the new token string.

The example script:

Defines the account API token used to authenticate on the Codacy API, the Git provider, the organization name, and the repository name passed as an argument to the script.
Calls the endpoint createRepositoryApiToken to create a new project API token and uses jq to obtain only the created token string.

#!/bin/bash

CODACY_API_TOKEN="<your account API token>"
GIT_PROVIDER="<your Git provider>" # gh, ghe, gl, gle, bb, or bbe
ORGANIZATION="<your organization name>"
REPOSITORY=$1

curl -sX POST "https://app.codacy.com/api/v3/organizations/$GIT_PROVIDER/$ORGANIZATION/repositories/$REPOSITORY/tokens" \
     -H "api-token: $CODACY_API_TOKEN" \
| jq -r ".data | .token"

Example usage and output

$ ./create-token.sh website
<new project API token>

Example: Creating project API tokens for all repositories in an organization#

This example creates new project API tokens for all the repositories in an organization and outputs a comma-separated list of repository names and corresponding token strings.

The example script:

Defines the account API token used to authenticate on the Codacy API, the Git provider, and the organization name.
Calls the endpoint listOrganizationRepositories to retrieve the list of repositories in the organization.
Uses jq to select only the name of the repositories.
Asks for confirmation from the user before making any changes.
For each repository, calls the endpoint createRepositoryApiToken to create a new project API token and uses jq to obtain only the created token string.
Outputs a comma-separated list of the repository names and the corresponding new token strings.
Pauses a few seconds between requests to the Codacy API to avoid rate limiting.

#!/bin/bash

CODACY_API_TOKEN="<your account API token>"
GIT_PROVIDER="<your Git provider>" # gh, ghe, gl, gle, bb, or bbe
ORGANIZATION="<your organization name>"

repositories=$(curl -sX GET "https://app.codacy.com/api/v3/organizations/$GIT_PROVIDER/$ORGANIZATION/repositories" \
                    -H "api-token: $CODACY_API_TOKEN" \
               | jq -r ".data[] | .name")

count=$(echo "$repositories" | wc -l)
read -p "Create project tokens for $count repositories? (y/n) " choice
if [ "$choice" = "y" ]; then
    echo "$repositories" | while read repository; do
        echo -n "$repository,"
        curl -sX POST "https://app.codacy.com/api/v3/organizations/$GIT_PROVIDER/$ORGANIZATION/repositories/$repository/tokens" \
             -H "api-token: $CODACY_API_TOKEN" \
        | jq -r ".data | .token"
        sleep 2 # Wait 2 seconds
    done
else
    echo "No changes made.";
fi

Example output:

chart,<new project API token>
docs,<new project API token>
website,<new project API token>
[...]

Important

For the sake of simplicity, the example doesn't consider paginated results obtained from the Codacy API. Learn how to use pagination to ensure that you process all results returned by the API.

Example: Listing the project API tokens for a repository#

This example lists all project API tokens created for a repository.

The example script:

Defines the account API token used to authenticate on the Codacy API, the Git provider, the organization name, and the repository name passed as an argument to the script.
Calls the endpoint listRepositoryApiTokens to list the project API tokens available on the repository and uses jq to obtain only the token strings, or exit with a non-zero status if the repository doesn't have any project API tokens created yet.

#!/bin/bash
CODACY_API_TOKEN="<your account API token>"
GIT_PROVIDER="<your Git provider>" # gh, ghe, gl, gle, bb, or bbe
ORGANIZATION="<your organization name>"
REPOSITORY=$1

curl -sX GET "https://app.codacy.com/api/v3/organizations/$GIT_PROVIDER/$ORGANIZATION/repositories/$REPOSITORY/tokens" \
     -H "api-token: $CODACY_API_TOKEN" \
| jq -er ".data[] | .token"

Example usage to obtain only the project API token created most recently for the repository:

$ ./list-tokens.sh website | head -n 1
<last project API token created>

Creating project API tokens programmatically#

Example: Creating a project API token for a single repository#

Example: Creating project API tokens for all repositories in an organization#

Example: Listing the project API tokens for a repository#

See also#

Share your feedback 📢