From fdebbb4fe4859af9feb7af8dcd8e63d5faff6bec Mon Sep 17 00:00:00 2001 From: Pedro Pereira Date: Thu, 6 Aug 2026 14:09:28 +0100 Subject: [PATCH] doc: Document repository API token creation and scope OD-395 Cover name rules, mandatory 1-year expiry, the 13 allowed operations, and expired-token handling for repository tokens. Co-Authored-By: Claude Sonnet 5 --- docs/codacy-api/api-tokens.md | 30 ++++++++++++++++++++++++- docs/codacy-api/using-the-codacy-api.md | 5 ++++- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/codacy-api/api-tokens.md b/docs/codacy-api/api-tokens.md index ab1fbd220b..3884517d4d 100644 --- a/docs/codacy-api/api-tokens.md +++ b/docs/codacy-api/api-tokens.md @@ -47,7 +47,7 @@ To delete an account API token, click the trash icon in the Actions column of th ## Generating and revoking repository API tokens {: id="repository-api-tokens"} -Repository API tokens are defined on **individual repositories**. Each repository API token only authorizes access to the corresponding repository. +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](#repository-api-token-operations); 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](examples/creating-repository-api-tokens-programmatically.md) or using the Codacy UI: @@ -55,13 +55,41 @@ You can create new repository API tokens programmatically [using the Codacy API] 1. 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. 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](images/codacy-api-tokens-repository.png) +!!! note + Repository API tokens created before expiration dates became mandatory keep working without an expiration date — they aren't retroactively required to have one. + +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 **X** next to the token. 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"}`. +### What repository API tokens can do on API v3 {: id="repository-api-token-operations"} + +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: + +- [Get a repository](https://api.codacy.com/api/api-docs#getrepository) +- [Get a repository with analysis information](https://api.codacy.com/api/api-docs#getrepositorywithanalysis) +- [Get the analysis tools settings of a repository](https://api.codacy.com/api/api-docs#listrepositorytools) +- [Configure an analysis tool for a repository](https://api.codacy.com/api/api-docs#configuretool) +- [Get the patterns configuration for a tool in a repository](https://api.codacy.com/api/api-docs#listrepositorytoolpatterns) +- [Update the patterns configuration for a tool in a repository](https://api.codacy.com/api/api-docs#updaterepositorytoolpatterns) +- [Get the patterns overview for a tool in a repository](https://api.codacy.com/api/api-docs#toolpatternsoverview) +- [Get the languages settings of a repository](https://api.codacy.com/api/api-docs#getrepositorylanguages) +- [List issues in a repository](https://api.codacy.com/api/api-docs#searchrepositoryissues) +- [Get an overview of the issues in a repository](https://api.codacy.com/api/api-docs#issuesoverview) +- [Return analysis results for the commits in a branch](https://api.codacy.com/api/api-docs#listrepositorycommits) +- [Reanalyze a specific commit in a repository](https://api.codacy.com/api/api-docs#reanalyzecommitbyid) +- [List ignored files in a repository](https://api.codacy.com/api/api-docs#listignoredfiles) + +For any other endpoint, including creating, listing, or revoking API tokens themselves, use an [account API token](#account-api-tokens) instead. + ## See also - [Adding coverage to your repository](../coverage-reporter/index.md) diff --git a/docs/codacy-api/using-the-codacy-api.md b/docs/codacy-api/using-the-codacy-api.md index a2cf5a4e54..084c089605 100644 --- a/docs/codacy-api/using-the-codacy-api.md +++ b/docs/codacy-api/using-the-codacy-api.md @@ -75,10 +75,13 @@ Codacy supports two API versions but we strongly recommend using the new API v3 Most API endpoints require that you authenticate using an API token. After [obtaining the necessary tokens](api-tokens.md), include them in your request headers using the format `api-token: ` or `project-token: `. !!! note - Currently, all API v3 endpoints that require authentication must use **account API tokens**, while the API v2 endpoints require either **account or repository API tokens**. + Most API v3 endpoints that require authentication must use an **account API token**. A [smaller set of repository-scoped endpoints](api-tokens.md#repository-api-token-operations) also accept a **repository API token**, scoped to that single repository. All API v2 endpoints accept either an account or a repository API token. Performing `GET` requests for public repositories doesn't require authentication. +!!! note + Repository API tokens always have an expiration date (up to one year). A request authenticated with an expired repository API token is rejected with a distinct "token expired" error, rather than the generic error you'd get from an invalid or unknown token — see [repository API tokens](api-tokens.md#repository-api-tokens). + For example, to make a request to an API v3 endpoint that requires an account API token: ```bash