Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
pedrobpereira wants to merge 1 commit into
base: master
Choose a base branch
from
+33 −2
Draft

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion docs/codacy-api/api-tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,21 +47,49 @@

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

Check failure on line 50 in docs/codacy-api/api-tokens.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Dashes] Remove the spaces around ' — '.

Raw Output:
{"message": "[Microsoft.Dashes] Remove the spaces around ' — '.", "location": {"path": "docs/codacy-api/api-tokens.md", "range": {"start": {"line": 50, "column": 147}}}, "severity": "ERROR"}

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

Check failure on line 59 in docs/codacy-api/api-tokens.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Dashes] Remove the spaces around ' — '.

Raw Output:
{"message": "[Microsoft.Dashes] Remove the spaces around ' — '.", "location": {"path": "docs/codacy-api/api-tokens.md", "range": {"start": {"line": 59, "column": 150}}}, "severity": "ERROR"}

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

Check failure on line 67 in docs/codacy-api/api-tokens.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Dashes] Remove the spaces around ' — '.

Raw Output:
{"message": "[Microsoft.Dashes] Remove the spaces around ' — '.", "location": {"path": "docs/codacy-api/api-tokens.md", "range": {"start": {"line": 67, "column": 115}}}, "severity": "ERROR"}

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)
Expand Down
5 changes: 4 additions & 1 deletion docs/codacy-api/using-the-codacy-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
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).

Check failure on line 83 in docs/codacy-api/using-the-codacy-api.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Dashes] Remove the spaces around ' — '.

Raw Output:
{"message": "[Microsoft.Dashes] Remove the spaces around ' — '.", "location": {"path": "docs/codacy-api/using-the-codacy-api.md", "range": {"start": {"line": 83, "column": 260}}}, "severity": "ERROR"}

For example, to make a request to an API v3 endpoint that requires an account API token:

```bash
Expand Down
Loading