[lelia]

Summary

Socket Basics needs two API token scopes: full-scans:create and socket-basics:read. The docs named them full-scans and socket-basics, which aren't valid scope names, and said nothing about Socket Tier 1 or about what a missing scope does. A missing scope never fails the run. It only logs, so a misconfigured token goes unnoticed.

Changes

• New "API token scopes" subsection under Socket Integration in docs/parameters.md:
  • The least-privilege scope set.
  • Every Socket API call by run type (dashboard configuration, result upload, Tier 1), with the scope each endpoint checks, when it's called, and what a failure logs. Scopes come from the API reference.
  • Three Tier 1 endpoints aren't in the reference. Two check full-scans:create. The engine-download endpoint, coana-cli/artifacts, works with any valid token.
• Scope names corrected in README.md, docs/github-action.md and docs/local-install-docker.md. The README keeps a short version that links to the new subsection.
• Things worth knowing that weren't documented:
  • On an Enterprise org, a key without socket-basics:read makes the dashboard-config step fail. That step also throws away the org it discovered, so results don't upload unless SOCKET_ORG is set.
  • The dashboard-config step reads only SOCKET_SECURITY_API_KEY, SOCKET_SECURITY_API_TOKEN and INPUT_SOCKET_SECURITY_API_KEY. A key set only as SOCKET_API_KEY skips it.
  • Tier 1 passes the key to the Socket npm CLI as SOCKET_SECURITY_API_KEY, but that CLI prefers SOCKET_CLI_API_TOKEN, SOCKET_CLI_API_KEY or SOCKET_SECURITY_API_TOKEN when one is set. If several are set to different tokens, Tier 1 can use a different token from the rest of the run.
  • The upload creates a missing repository, and an organization API token needs only full-scans:create for that.
  • The CI/CD key guide includes full-scans:create but not socket-basics:read.
• For the heavy image's bundled socketcli, the docs link to its permissions guide rather than repeating it. Improve documentation for requisite API token permissions socket-python-cli#353 adds that guide, so merge this after #353, or at the same time.

Questions this answers

• Does Socket Basics need security-policy:read or the triage:* scopes? No. It makes no triage or security-policy calls, and neither does socketcli. So those three scopes on the CI/CD key guide aren't there for either Python tool. The npm CLI's socket ci uses security-policy:read.
• Does it share the CLI's silent diff-scans fallback? No. Socket Basics never creates diff scans. It uploads a full scan, and Tier 1 runs socket scan reach, neither of which calls the diff-scans endpoints.
• Where should the docs live? Socket Basics has no page on docs.socket.dev, so this PR puts the scope docs in the repo (docs/parameters.md, with a short version in the README). A docs-site page would be a separate change.

Related PRs

• Improve documentation for requisite API token permissions socket-python-cli#353: the same audit for the CLI. This PR links to its troubleshooting section, so merge #353 first.
• Document the API token scopes each SDK method needs socket-sdk-python#130: the same audit for the Python SDK.
• SocketDev/docs#195: the CI/CD key guide's new per-tool scope table links to this PR's #api-token-scopes section, so merge this PR before that one.

Testing

Docs only. python3 scripts/check_release_docs.py --check passes. Each call was traced in the source: the direct socketdev SDK calls, and the published Socket npm CLI that runs socket scan reach for Tier 1. Options passed through socket_additional_params can make more calls, and the docs say those aren't covered.

Fixes: CE-463
Refs: CE-384

[cursor]

PR Summary

Low Risk
Documentation-only updates with no runtime or configuration code changes.

Overview
Documentation now uses the actual Socket API token scope names — full-scans:create and socket-basics:read — instead of the invalid full-scans / socket-basics labels. README, github-action, local-install-docker, and parameters are aligned, with troubleshooting text explaining that missing scopes log errors but do not fail the exit code, and that lacking socket-basics:read on Enterprise can drop org discovery so uploads need SOCKET_ORG.

The main addition is a new ### API token scopes section in docs/parameters.md: least-privilege scope table, API calls grouped by dashboard config, result upload, and Socket Tier 1 (with per-endpoint scope requirements and failure behavior), plus notes on which env vars participate in dashboard loading, Tier 1 CLI token precedence, and a link to the Python CLI permissions doc.

^{Reviewed by Cursor Bugbot for commit 66eba35. 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 66eba35. Configure here.}