Improve documentation for requisite API token permissions

[lelia]

⚠️ This PR is not ready for review until the below TODO regarding scope names is complete.

Why

The repo documented exactly one thing about token permissions: a troubleshooting note about the diff-scans comparison path. It had three problems.

It described the APIAccessDenied fallback as a PR/MR-only condition. The comparison also runs on plain pushes — socketcli.py:846 calls create_new_diff in the non-PR/MR branch — so a pipeline that only scans pushes hits it and reads the note as not applying.

It listed full-scans:list alongside the two diff-scans:* scopes. The streaming fallback is GET orgs/{org}/full-scans/diff, itself a full-scans read, so if the fallback returns results the token already has that permission. Readers were pointed at a permission they demonstrably had.

And it never documented the baseline set, conceding as much with "in addition to whatever the scan itself needs". A token could not be provisioned from the docs.

The setup guide omits two scopes this CLI requires

The published CI/CD token setup guide tells readers to select nine scopes:

repo:list, repo:create, repo:update, security-policy:read, triage:alerts-list, triage:alerts-update, full-scans:list, full-scans:create, packages:list

It does not list diff-scans:create or diff-scans:list.

Every diff-producing run tries the diff-scans endpoints first, so a token provisioned exactly as that guide describes fails that call with APIAccessDenied and silently falls back to the legacy streaming comparison. The only signal is a warning in the log. This is not a misconfiguration a user can be blamed for — following the documented setup produces it, and it affects every CLI user who provisioned that way.

The converse also holds. socketcli makes no triage or security-policy API calls at all, verified against the full SDK call surface, so security-policy:read, triage:alerts-list and triage:alerts-update are not exercised by this CLI. They are on the guide's list for other Socket tooling.

The guide itself is separate tooling and out of scope here; this PR documents the gap so CLI users can work around it.

What changed

docs/troubleshooting.md carries the substance: three tables covering what every run calls, what diff-producing runs add, and what each flag adds; the nine documented scope names plus the two missing ones, mapped to the calls they cover; and sections on the APIAccessDenied fallback, temporary baseline scans, reachability vs. full-scan IDs, and the exit-2 caveat.

Supporting changes: permissions pointers in README.md, docs/cli-reference.md, and docs/ci-cd.md; all four accepted token environment variables documented in priority order; and a $SOCKET_API_TOKEN reference in the GitLab requirements section corrected to SOCKET_SECURITY_API_TOKEN.

TODO

• Confirm the scope identifiers that the setup guide does not publish.

Two calls every run makes — GET organizations and GET report/supported — map to no scope on the guide's list. They appear to be available to any valid org token, but that is inference, and the docs currently say so. Also unmapped: license-metadata, export/cdx, the reachability manifest upload, and finalize_tier1.

The scope-to-call mapping in the tables is likewise inferred from the names, since the guide publishes no per-endpoint mapping. It is labelled as inferred in the docs. Someone who owns the scope definitions should confirm both before this leaves draft.

Notes for the reviewer

Every claim was verified against 2.8.1, not the 2.7.2 tree the audit started on.

README.md's exit code table now notes that exit 2 also covers repository lookup/creation failure, and that neither exit-code flag remaps it. That behavior is a bug, tracked separately — this PR only documents it.

The changelog entry is under ## Unreleased rather than a version number. A branch section header matching a version that ships first gets silently deleted on rebase with no conflict marker, and coana bump PRs land unpredictably. Whoever cuts the next patch needs to rename that header, or it ends up orphaned under a newer section.

No version bump: version-check.yml only triggers on socketsecurity/**, pyproject.toml, uv.lock, and its own path, so a .md-only PR never runs the gate.

Fixes: CE-461
Refs: CE-384, CE-460

---

Note

Low Risk
Markdown-only documentation changes with no runtime or dependency changes.

Overview
Documentation-only PR that expands how to provision Socket API tokens for socketcli and fixes several misleading permission/exit-code notes.

The main change is a rewritten docs/troubleshooting.md#api-token-permissions section: tables for API calls on every run, on diff-producing runs, and per flag; scope-to-call mapping; callout that the published CI/CD setup guide omits diff-scans:create and diff-scans:list (so tokens following that guide silently fall back to legacy comparison); and note that triage/security-policy scopes are unused by this CLI.

Scan-comparison guidance is corrected so APIAccessDenied fallback applies to any diff-producing run (including default-branch pushes), not only PR/MR, and clarifies that missing grants are the two diff-scans:* scopes—not full-scans:list when the streaming fallback already works.

New troubleshooting sections document expected “failure-like” behavior: temporary empty baselines on first scan, reachability IDs vs full-scan IDs, and exit 2 for repository lookup/creation permission gaps (including that --disable-blocking and --exit-code-on-api-error do not remap it). README.md exit-code table and precedence notes are updated to match.

docs/cli-reference.md documents all four accepted token env vars in priority order and fixes the GitLab requirements reference from $SOCKET_API_TOKEN to SOCKET_SECURITY_API_TOKEN. Pointers to the permissions guide are added in README.md, docs/cli-reference.md, and docs/ci-cd.md. CHANGELOG.md records the work under Unreleased.

^{Reviewed by Cursor Bugbot for commit 72c2f29. Configure here.}

[lelia]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 72c2f29. Configure here.}