Skip to content

Improve documentation for requisite API token permissions #353

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
lelia wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Improve documentation for requisite API token permissions #353

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
468ea97
Document the API token permissions a run actually needs
lelia Sep 11, 2026
1e99f3c
Name the token scopes and flag the two the setup guide omits
lelia Sep 11, 2026
69f8871
Correct which runs compare, after the 2.9.0 flow change
lelia Sep 23, 2026
c7b9938
Bump to 2.9.8
lelia Sep 23, 2026
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
Prev Previous commit
Next Next commit
Name the token scopes and flag the two the setup guide omits 
The permission tables described endpoints but deferred on scope names, since
nothing in this repo or the SDK publishes them. The public CI/CD token setup
guide does: nine scopes, which the docs now name and map to the calls they
cover.

That guide omits `diff-scans:create` and `diff-scans:list`. Every
diff-producing run tries the diff-scans endpoints first, so a token
provisioned exactly as documented always fails that call and falls back to the
legacy streaming comparison, with a warning as the only signal. Anyone
following the documented setup hits this.

The converse is also worth stating: `socketcli` makes no triage or
security-policy calls, so three of the nine scopes the guide lists are not
exercised by this CLI.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
  • Loading branch information
@lelia @claude
lelia and claude committed Sep 23, 2026
commit 1e99f3cbd5e36023b9353969e577a4f1b7e3307b
8 changes: 6 additions & 2 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,12 @@

- Documented the API calls a run actually makes, so a token can be provisioned without
trial and error: what every run calls, what diff-producing runs add, and what each
flag adds. Only the diff-scans scope names are published, so the remaining calls are
described by endpoint, with a pointer to support for exact scope identifiers.
flag adds, with the scope names mapped to them.
- Recorded that the published CI/CD token setup guide does not list `diff-scans:create`
or `diff-scans:list`. Every diff-producing run needs both, so a token provisioned
exactly as that guide describes always falls back to the legacy comparison path.
Recorded the converse too: `socketcli` makes no triage or security-policy calls, so
three of the nine scopes that guide lists are not exercised by this CLI.
- Corrected the scan-comparison guidance. The `APIAccessDenied` fallback was documented
as a PR/MR-only condition, but it applies to any run that produces a diff, including
plain pushes on the default branch. The guidance also listed `full-scans:list`
Expand Down
41 changes: 36 additions & 5 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,42 @@ These are exercised on any invocation, regardless of flags:
| `GET orgs/{org}/full-scans/diff` | Legacy streaming comparison (fallback path) |
| `GET orgs/{org}/full-scans/{id}` | Resolve a baseline for `--base-scan-id` / `--base-commit-sha` |

The diff-scans path is the one with published scope names: `diff-scans:create`,
`diff-scans:list` and `full-scans:list`. For the rest of the calls above, grant the
token access to the corresponding resource; if you need the exact scope identifiers to
provision a least-privilege token, ask Socket support rather than inferring them from
the endpoint paths.
### Which scopes to grant

The [CI/CD token setup guide](https://docs.socket.dev/docs/create-socket-api-key-for-cicd)
tells you 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`

**That list is not sufficient for this CLI.** It does not include `diff-scans:create`
or `diff-scans:list`, which every diff-producing run needs. A token provisioned exactly
as that guide describes will always fall back to the legacy comparison path — see the
next section. Grant those two in addition.

Going the other way, `socketcli` makes no triage or security-policy API calls at all,
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.

Mapping the remaining scopes to the calls above (inferred from the names; the setup
guide does not publish a per-endpoint mapping):

| Scope | Covers |
|:---|:---|
| `repo:list` | Repository lookup |
| `repo:create` | Repository creation on lookup failure |
| `repo:update` | Setting the scan as repository head / default branch |
| `full-scans:create` | Creating the new scan |
| `full-scans:list` | Reading scans, metadata, streams, and the legacy `full-scans/diff` comparison |
| `diff-scans:create` | Creating the comparison |
| `diff-scans:list` | Resolving and polling the comparison |
| `packages:list` | `POST purl` for license text |

`GET organizations` and `GET report/supported` are not covered by any scope on the
guide's list and appear to be available to any valid org token. If you are provisioning
a least-privilege token and one of these fails, ask Socket support — the scope
identifiers for them are not published.

### What individual flags add

Expand Down