[nathanfishcircleci]

Summary

• Personal API tokens can now be created with a Read, Write, or Admin scope. Document this on the managing API tokens page, including a table of what each scope allows and a note that a scope is a ceiling bounded by the user's role.
• Add a scope selection step to the shared create-a-personal-api-token steps (also included in the API v3 developers guide) and to the rotation steps.
• Update the OAuth dynamic client registration note, which said manually created tokens always carry full permissions.
• Scope content is wrapped in ifndef::server[], so Server pages are unchanged.

Test plan

• Build the docs and check the new "Personal API token scopes" section and anchors on the managing API tokens page
• Confirm the Server build omits the scope content
• Vale passes

🤖 Generated with Claude Code

[circleci-factory-bot]

FAIL 🔴 author-membership ⚙️ author not in allow-list

nathanfishcircleci is not in the allow-listed users; allowed: rosieyohannan

WARN 🟡 documentation ✨ Scopes section repeats least-privilege advice

Flagged one block:

• docs/guides/modules/toolkit/pages/managing-api-tokens.adoc:66 (wordiness): the "Use scoped tokens to issue narrowly-scoped access…" paragraph explains in general terms why least privilege helps. It repeats the "Choose the narrowest scope that meets your needs" step, which comes from the partial included earlier on the same page.

The rest is concise end-user documentation that readers need: the new procedure steps, the scope table, the paragraph explaining that a scope can't exceed your role, the note on tokens created before scopes and on changing scope, and the updated OAuth note.

WARN 🟡 impact-matches-intent ✨ Vantage/Finout pages still say no token scopes

The new scope docs are correctly wrapped in ifndef::server[] and reach every page that includes the shared partial (managing-api-tokens.adoc, api-v3-developers-guide.adoc). Two customer-facing pages still contradict the new Cloud behavior:

• docs/guides/modules/plans-pricing/pages/integrate-with-vantage-for-cost-management.adoc:36
• docs/guides/modules/plans-pricing/pages/integrate-with-finout-for-cost-management.adoc:37

Both still say "CircleCI personal API tokens do not support fine-grained permission scoping. The token you create will have full access...". This PR fixes the same stale claim in the OAuth note but misses these two. Update them, for example by recommending a Read scope for cost-management integrations.

SKIP ⚪ 6 skipped check(s)

SKIP ⚪ api-auth-and-design ✨ Docs-only token-scope update; no API surface

I judged this against the circleci/circleci-docs diff at bb0f5d2. The change only edits AsciiDoc pages so they document Read/Write/Admin scopes for personal API tokens. It adds no V3 route, handler, request or response type, or auth code, and it changes nothing that public-api-service exposes.

1. Applicable checklist items: none. No V3 design item (envelope shape, path rules, naming, scope rules) and no auth audit item (C1–C3, H1–H5, M1–M3, L1–L3) applies to documentation prose.
2. Public exposure: this change creates or exposes no publicly reachable route, so there is nothing in public-api-service or a backend service to judge.

SKIP ⚪ agents-md-respect ✨ Cloud-only token scope docs follow style rules

I found no rule violations in this diff.

1. The new Cloud-only scope content is wrapped in balanced ifndef::server[] blocks, each directive on its own line and none inside tabs or mid-sentence.
2. The new table uses the [.table-scroll] wrapper.
3. The [#personal-api-token-scopes] ID is kebab-case, and the xref link text is title case.
4. Every xref target exists. The module-less xref in the shared partial resolves because both pages that include it are in toolkit, and the partial already uses that form elsewhere.

SKIP ⚪ git-hygiene ⚙️ git history is clean

no merge commits, not behind main, no more than 5 commits, and no problems with the commit messages

SKIP ⚪ go-best-practices ⚙️ no Go changes to review

no reviewable Go changes among 3 changed file(s)
ignoring 3 non-Go files: docs/guides/modules/ROOT/partials/shared-sections/create-a-personal-api-token.adoc, docs/guides/modules/toolkit/pages/managing-api-tokens.adoc, docs/guides/modules/toolkit/pages/oauth-dynamic-client-registration.adoc

SKIP ⚪ reduces-risk ⚙️ non-test files changed

change touches 3 non-test file(s): docs/guides/modules/ROOT/partials/shared-sections/create-a-personal-api-token.adoc, docs/guides/modules/toolkit/pages/managing-api-tokens.adoc, docs/guides/modules/toolkit/pages/oauth-dynamic-client-registration.adoc

SKIP ⚪ server-compat ⚙️ no new required config keys

no new env.MustGet calls added in this PR

_{🤖 factory-bot · codeowner mode · reviewed @ 2026-10-07T18:26:18Z · re-request a review to re-run
[trace:9c57aa7] [bot fa395a5] [config 7fa3551] [target bb0f5d2]}