docs: Document repository API token creation and scope OD-395 by pedrobpereira · Pull Request #2725 · codacy/docs

pedrobpereira · 2026-08-06T13:21:14Z

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

If relevant, include the Jira issue key at the end of the pull request title
Perform a self-review of the changes
Fix any issues reported by the CI/CD

Manual Testing

Add manual testing evidence here (steps, screenshots, environment).

github-actions · 2026-08-06T13:22:13Z

Overall readability score: 53.81 (🟢 +0.02)

File	Readability
index.md	60.26 (🟢 +1.36)
using-the-codacy-api.md	55.65 (🔴 -0.08)
api-tokens.md	70.97 (🟢 +2.84)

View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File	Readability	FRE	GF	ARI	CLI	DCRS
index.md	60.26	40.04	9.85	11	11.94	7.26
	🟢 +1.36	🔴 -0.2	🟢 +0.18	🟢 +0.1	🟢 +0.23	🟢 +0.19
using-the-codacy-api.md	55.65	42.41	11.2	13.1	11.84	7.19
	🔴 -0.08	🔴 -0.2	🔴 -0.08	🔴 -0.1	🟢 +0.05	🟢 +0.05
api-tokens.md	70.97	40.45	8.17	9.2	10.43	6.32
	🟢 +2.84	🟢 +0.21	🟢 +0.5	🟢 +0.3	🟢 +0.23	🟢 +0.37

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	53.81	42.85	10.97	12.39	12.3	8.03
	🟢 +0.02	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0

View metric targets

Metric	Range	Ideal score
Flesch Reading Ease	100 (very easy read) to 0 (extremely difficult read)	60
Gunning Fog	6 (very easy read) to 17 (extremely difficult read)	8 or less
Auto. Read. Index	6 (very easy read) to 14 (extremely difficult read)	8 or less
Coleman Liau Index	6 (very easy read) to 17 (extremely difficult read)	8 or less
Dale-Chall Readability	4.9 (very easy read) to 9.9 (extremely difficult read)	6.9 or less

codacy-production · 2026-08-06T13:22:29Z

Up to standards ✅

🟢 Issues0 issues

Results:
0 new issues
View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

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>

codacy-production

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}

codacy-production · 2026-08-11T12:44:33Z


 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.


_{🟡 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.

codacy-production · 2026-08-11T12:44:33Z


+### 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:


_{🟡 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 operationson the repository it was created for (unlike the legacy **API v2**, which allows access to all endpoints for that repository):

codacy-production · 2026-08-11T12:44:33Z

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


_{⚪ 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>

…D-395 Add screenshots for the repository API token flow: the create modal, the custom date option, the newly created token, the bulk delete, and a repository with a token that never expires. Replace the account API token screenshots, which no longer matched the UI. Correct the parts of the page the new screenshots contradicted: - Repository API tokens are under Settings > API tokens, not Integrations. - Account API tokens can no longer be created without an expiration date, and are capped at one year like repository tokens. - Tokens are revoked with the trash icon in the Actions column, or in bulk by selecting them and clicking Delete tokens. - Document that the token value is shown only once, immediately after creation. Add a recommendation to replace tokens without an expiration date, in both sections, including the order to follow so that live integrations don't break. Remove two images that no longer have any reference and no longer match the UI: codacy-api-tokens-account.png and codacy-api-tokens-repository.png. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

claudiacodacy · 2026-08-14T08:59:26Z

 - Upload to Codacy the results of [running client-side analysis tools](../repositories-configure/local-analysis/client-side-tools.md)
 - [Authenticate when using the Codacy API](using-the-codacy-api.md#authenticating-requests)
- [Authenticate with the Codacy Cloud CLI](../codacy-cloud-cli/index.md#authentication)
+- [Authenticate with the Codacy Cloud CLI](../codacy-cloud-cli/index.md#authentication) (account API tokens only — the Codacy Cloud CLI doesn't currently support repository API tokens)


It doesnt? :sus: what is this then? OD-489

Good catch, you're right. OD-489 is Done (13 Aug) and codacy-cloud-cli#37 "feat: Add repository (project) token support" merged on the 11th, so the CLI does support repository tokens now. Claim removed in 8182527.

can you update this?

Done in 69944d2 — and you were right to push back. Deleting the sentence made the page silent rather than correct: the Codacy Cloud CLI page it links to still documented account API tokens only, so there was nowhere saying repository tokens work.
That section now covers, from codacy-cloud-cli v1.9.0:
the option --repository-token and the CODACY_PROJECT_TOKEN environment variable, and that codacy login only accepts account API tokens
the precedence: --repository-token > CODACY_PROJECT_TOKEN > CODACY_API_TOKEN > stored credentials
that commands outside the operations a repository token authorizes fail immediately rather than returning an Unauthorized error, and that codacy repository omits pull request and coverage data, listing them under unavailable in its JSON output

claudiacodacy · 2026-08-14T08:59:27Z

+
+![A newly created repository API token, with its value displayed once](images/codacy-api-tokens-repository-created.png)
+
+!!! important


can you ask claude to update the branch to master and review the PR according to the formatting rules? XD im wondering how many admonitions we have here and how many we need

Branch updated from master.
On admonitions: the page has 4 in the file, plus one pulled in from assets/includes/api-token-warning.md. The two !!! important blocks added along with the screenshots were the extra weight, so the account-level one is now a plain paragraph and this one is back to !!! note, as it was before. Net admonitions added by this PR: zero. Vale passes.

claudiacodacy · 2026-08-14T08:59:27Z

Why is the name blurred here but not blurred on the other screen docs/codacy-api/images/codacy-api-tokens-repository-bulk-delete.png

Fixed by unblurring this one in 8182527. pt-caa4da16ab2e is a generated name rather than a token value, so it belongs in the same category as the names in the bulk delete screenshot. The only thing still pixelated is the actual token value in the created-token screenshot, which does need to stay that way.

- The Codacy Cloud CLI does support repository API tokens since OD-489 shipped, so drop the claim that it doesn't. - Reword the notes on tokens created before expiration dates became mandatory, following Claudia's suggestion. - Turn the account-level note into a paragraph and the repository one back into a note, so the page keeps the same number of admonitions it had before the screenshots were added. - Stop blurring the token name in the never-expires screenshot: it's a generated name rather than a token value, and it was inconsistent with the bulk delete screenshot, which shows names unblurred. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

LipeGheno · 2026-08-14T09:33:15Z

One open question, since it predates this PR and I couldn't settle it from screenshots: the account section still says "By hovering a token, you are able to copy its value." The account tokens table now masks the value (xxxxxxxxxxxxxxxxxLli), so it isn't clear whether hover-to-copy still exists. I left the line untouched — @claudiacodacy @andrzej-janczak, can one of you confirm in the UI?

Removing the claim that the CLI doesn't support repository API tokens left the documentation silent about it. Document it instead, now that OD-489 shipped in codacy-cloud-cli v1.9.0: - The option --repository-token and the CODACY_PROJECT_TOKEN environment variable, and that codacy login only takes account API tokens. - The precedence between the two tokens, the option, and stored credentials. - That commands outside the operations a repository API token authorizes fail immediately, and that codacy repository omits pull request and coverage data. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Per .claude/reference/formatting.md, checked against the docs-review-page rubric: - api-tokens.md: the two "replace grandfathered tokens" notes packed a 3-step sequence the reader must follow in order into one comma-chained sentence. Converted to a nested numbered list in both places, without adding an admonition, so the admonition count from the last round stays the same. - codacy-cloud-cli/index.md: split ## Authentication into ### Account API tokens and ### Repository API tokens, matching the ### subsection pattern already used by every other multi-topic section on this page (## What you can do, ## Example workflows). Moved "To remove your stored credentials" under Account API tokens, since codacy logout only applies to stored login credentials, not to a repository token passed via flag or env var. Verified with mkdocs build --strict: no broken anchors, no duplicate heading ids on the page. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

github-actionsBot temporarily deployed to Netlify August 6, 2026 13:22 Inactive

pedrobpereira force-pushed the doc/repo-tokens-product-page-OD-395 branch from fd791d7 to 5234b79Compare August 6, 2026 13:28

github-actionsBot temporarily deployed to Netlify August 6, 2026 13:30 Inactive

pedrobpereira force-pushed the doc/repo-tokens-product-page-OD-395 branch from 5234b79 to 8b7d7baCompare August 6, 2026 13:32

github-actionsBot temporarily deployed to Netlify August 6, 2026 13:34 Inactive

doc: Document repository API token creation and scope OD-395
fdebbb4
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 8b7d7ba to fdebbb4Compare August 6, 2026 13:35

github-actionsBot temporarily deployed to Netlify August 6, 2026 13:36 Inactive

LipeGheno marked this pull request as ready for review August 11, 2026 12:43

LipeGheno requested a review from a team as a code owner August 11, 2026 12:43

codacy-productionBot reviewed Aug 11, 2026
View reviewed changes

github-actionsBot temporarily deployed to Netlify August 11, 2026 14:05 Inactive

LipeGheno requested review from andrzej-janczak and claudiacodacy August 14, 2026 08:36

github-actionsBot temporarily deployed to Netlify August 14, 2026 08:38 Inactive

claudiacodacy reviewed Aug 14, 2026
View reviewed changes

LipeGhenoand others added 2 commits August 14, 2026 10:29

Merge branch 'master' into doc/repo-tokens-product-page-OD-395
25d3061

github-actionsBot temporarily deployed to Netlify August 14, 2026 09:32 Inactive

github-actionsBot temporarily deployed to Netlify August 14, 2026 10:09 Inactive

github-actionsBot deployed to Netlify August 14, 2026 10:23 View deployment


		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.


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

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


		![A newly created repository API token, with its value displayed once](images/codacy-api-tokens-repository-created.png)

		!!! important

Uh oh!

Conversation

pedrobpereira commented Aug 6, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

👀 Live preview

🚧 To do

Manual Testing

Uh oh!

github-actionsBot commented Aug 6, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codacy-productionBot commented Aug 6, 2026

Up to standards ✅

Uh oh!

codacy-productionBot left a comment

Choose a reason for hiding this comment

Pull Request Overview

About this PR

Test suggestions

Uh oh!

codacy-productionBotAug 11, 2026

Choose a reason for hiding this comment

Uh oh!

codacy-productionBotAug 11, 2026

Choose a reason for hiding this comment

Uh oh!

codacy-productionBotAug 11, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LipeGheno commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

pedrobpereira commented Aug 6, 2026•
edited
Loading

github-actionsBot commented Aug 6, 2026•
edited
Loading