docs: Document repository API token creation and scope OD-395

docs/codacy-api/api-tokens.md

@@ -30,37 +30,89 @@
 
 1.  Click the button **Create API token** under **Account API tokens**.
 
-1. Select an expiration date from the modal options. You can select between a range of 7 days to 90 days, create a custom expiration date, or create a token with no expiration.
+1.  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](images/codacy-api-tokens-account.png)
-
-![Creating an account API token modal](images/codacy-api-tokens-account-modal.png)
+    ![Creating an account API token modal](images/codacy-api-tokens-account-modal.png)
 
 !!! 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.
 
-![Creating an account API token modal](images/codacy-api-tokens-account-table.png)
+![The account API tokens table](images/codacy-api-tokens-account-table.png)
 
 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.
+1.  Update every application or service that authenticates with the old token.
+1.  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 {: 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:
 
-1.  Open your repository **Settings**, tab **Integrations**.
+1.  Open your repository **Settings**, tab **API tokens**.
 
 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, 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](images/codacy-api-tokens-repository.png)
+    ![Creating a repository API token](images/codacy-api-tokens-repository-modal.png)
+
+    Selecting **Custom date** lets you pick any date up to one year from today:
+
+    ![Setting a custom expiration date for a repository API token](images/codacy-api-tokens-repository-modal-custom-date.png)
+
+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](images/codacy-api-tokens-repository-created.png)
+
+!!! 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.
+    1.  Update every application or service that authenticates with the old token, such as your CI pipelines.
+    1.  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](images/codacy-api-tokens-repository-never-expires.png)
+
+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](images/codacy-api-tokens-repository-bulk-delete.png)
+
+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 {: 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)
 
-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"}`.
+For any other endpoint, including creating, listing, or revoking API tokens themselves, use an [account API token](#account-api-tokens) instead.
 
 ## See also
 

docs/codacy-api/using-the-codacy-api.md

@@ -75,10 +75,13 @@
 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: <your account API token>` or `project-token: <your repository API 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
+    New 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

docs/codacy-cloud-cli/index.md

@@ -22,18 +22,32 @@ Alternatively, you can build from source. See the [GitHub repository](https://gi
 
 ## Authentication {: id="authentication"}
 
-Run `codacy login` and enter your API token when prompted. Codacy stores your credentials encrypted at `~/.codacy/credentials`.
+The CLI accepts both [account API tokens](../codacy-api/api-tokens.md#account-api-tokens) and [repository API tokens](../codacy-api/api-tokens.md#repository-api-tokens).
+
+### Account API tokens
+
+Run `codacy login` and enter the token when prompted. Codacy stores your credentials encrypted at `~/.codacy/credentials`. Get the token under **My Account > Access Management > API Tokens** in Codacy.
 
 ```bash
 codacy login
 ```
 
 For non-interactive environments such as CI/CD pipelines, set the `CODACY_API_TOKEN` environment variable instead. This takes precedence over stored credentials.
 
-Get your API token under **My Account > Access Management > API Tokens** in Codacy. See [API tokens](../codacy-api/api-tokens.md) for details.
-
 To remove your stored credentials, run `codacy logout`.
 
+### Repository API tokens
+
+Use the option `--repository-token` or set the `CODACY_PROJECT_TOKEN` environment variable. You can't use a repository API token with `codacy login`.
+
+```bash
+codacy issues gh my-org my-repo --repository-token <token>
+```
+
+Prefer a repository API token in CI/CD pipelines: unlike an account API token, it only grants access to a single repository. Because it authorizes [a limited set of operations](../codacy-api/api-tokens.md#repository-api-token-operations), commands outside that set fail immediately instead of contacting Codacy. The command `codacy repository` works, but omits the pull request and coverage data, listing what it skipped under `unavailable` in its JSON output.
+
+When more than one credential is available, the CLI uses the first of the option `--repository-token`, `CODACY_PROJECT_TOKEN`, `CODACY_API_TOKEN`, and the credentials stored by `codacy login`.
+
 ## Install the Codacy Skills {: id="install-the-codacy-skills"}
 
 The [Codacy Skills](https://github.com/codacy/codacy-skills) let your AI assistant interact with your Codacy data in plain language, without needing to remember command syntax: