docs: Document repository API token creation and scope OD-395 - #2725
Open
pedrobpereira wants to merge 2 commits into
Open
docs: Document repository API token creation and scope OD-395#2725pedrobpereira wants to merge 2 commits into
pedrobpereira wants to merge 2 commits into
Conversation
Contributor
|
Overall readability score: 53.92 (🔴 -0.01)
View detailed metrics🟢 - Shows an increase in readability
Averages:
View metric targets
|
Contributor
Up to standards ✅🟢 Issues
|
pedrobpereira
force-pushed
the
doc/repo-tokens-product-page-OD-395
branch
from
August 6, 2026 13:28
fd791d7 to
5234b79
Compare
pedrobpereira
force-pushed
the
doc/repo-tokens-product-page-OD-395
branch
from
August 6, 2026 13:32
5234b79 to
8b7d7ba
Compare
Cover name rules, mandatory 1-year expiry, the 13 allowed operations, and expired-token handling for repository tokens. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
pedrobpereira
force-pushed
the
doc/repo-tokens-product-page-OD-395
branch
from
August 6, 2026 13:35
8b7d7ba to
fdebbb4
Compare
LipeGheno
marked this pull request as ready for review
August 11, 2026 12:43
![codacy-production[bot]](https://avatars.githubusercontent.com/in/56611?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull Request Overview
The documentation updates generally align with the requirements for detailing Repository API token creation and scoping. However, the PR fails to document that token values remain fully visible (not masked) after creation, a detail explicitly mentioned in the PR intent. Additionally, the phrasing in some sections could lead to confusion between the restricted scope of API v3 tokens versus legacy API v2 behavior. Codacy results indicate the PR is up to standards with no new quality issues.
About this PR
- The PR description indicates that documentation would include a note about the token value staying 'fully visible after creation (not masked)', but this information is absent from the repository API tokens section.
Test suggestions
- Verify documentation of naming constraints for repository tokens.
- Verify documentation of the 1-year maximum expiration and absence of 'never-expire' option.
- Verify documentation of the 13 specific authorized operations for API v3.
- Verify documentation that legacy tokens without expiry are grandfathered.
- Verify mention of 'token value stays fully visible after creation (not masked)'
Prompt proposal for missing tests
Consider implementing these tests if applicable:
1. Verify mention of 'token value stays fully visible after creation (not masked)'
TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback
|
|
||
| 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. |
Contributor
There was a problem hiding this comment.
🟡 MEDIUM RISK
The PR description mentions that the documentation should state 'the token value stays fully visible after creation (not masked)'. This information is missing from this section of the diff.
|
|
||
| ### 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: |
Contributor
There was a problem hiding this comment.
🟡 MEDIUM RISK
Suggestion: The current phrasing suggests the following list applies to API v2, while it actually describes the restricted set for API v3.
Suggested change
| 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: | |
| On **API v3**, a repository API token authorizes only the following operations on the repository it was created for (unlike the legacy **API v2**, which allows access to all endpoints for that repository): |
| 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). |
Contributor
There was a problem hiding this comment.
⚪ LOW RISK
Suggestion: This statement is too absolute and contradicts the legacy token exception mentioned in the main documentation. Adding a qualifier improves accuracy.
Suggested change
| 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). | |
| 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). |
- Repository token names are unique per repository (confirmed by Andrzej Janczak), not just character-restricted. - The Codacy Cloud CLI doesn't currently support repository tokens (confirmed by Andrzej Janczak) — the intro list implied it did for both token types. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Changes
docs/codacy-api/api-tokens.md: document repository API token name rules, mandatory 1-year-max expiry (no never-expire option), that the token value stays fully visible after creation (not masked), grandfathered legacy tokens without an expiry, the distinct "token expired" error, and the full list of 13 operations a repository token can authorize (own repository only).docs/codacy-api/using-the-codacy-api.md: correct the auth section's outdated claim that all API v3 endpoints require an account token, and add a note on repository-token expiry/error behavior.👀 Live preview
https://doc-repo-tokens-product-page-od-395--docs-codacy.netlify.app
🚧 To do
Manual Testing
Add manual testing evidence here (steps, screenshots, environment).