Skip to content

docs: List the API token scopes Socket Basics needs - #140

Open
lelia wants to merge 2 commits into
mainfrom
lelia/api-token-scope-docs
Open

lelia wants to merge 2 commits into
mainfrom
lelia/api-token-scope-docs

Conversation

@lelia

@lelia lelia commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Socket Basics needs two API token scopes: full-scans:create and socket-basics:read. The docs named the scope groups, full-scans and socket-basics. Those work, because a group covers every scope in it, but full-scans grants more than Socket Basics uses. The docs also 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, accepts full-scans:create or fixes:list.
    • How scope groups relate to the scopes. socket-basics:read is the only scope in the socket-basics group, so selecting either is the same token: the dashboard shows both checked, and the API reports the scope as socket-basics.
  • README.md, docs/github-action.md and docs/local-install-docker.md now name the specific scopes. The README keeps a short version that links to the new subsection.
  • Organization discovery is described the same way everywhere: the organization is discovered from the key, and only on an Enterprise organization does that also need socket-basics:read.
  • 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.
    • A token created for the Socket CLIs may lack socket-basics:read, so check for it before relying on dashboard configuration.
  • 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 used security-policy:read before version 1.15.0.
  • 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

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

The docs named the scopes `full-scans` and `socket-basics`, which are not
scope names; the API checks `full-scans:create` and `socket-basics:read`.
They also left out that Socket Tier 1 needs `full-scans:create`, and that a
missing scope never fails the run.

- Add an API token scopes section to the parameters reference: a
  least-privilege scope table, then every Socket API call by step (dashboard
  configuration, result upload, Socket Tier 1) with the scope it checks, when
  it is called and how a denial shows up in the log
- Note that on an Enterprise organization a key without
  `socket-basics:read` also loses organization discovery, so `SOCKET_ORG`
  must be set for the upload
- Note which token variables each step reads, and that the Socket npm CLI
  prefers its own variables over the one Tier 1 passes
- Correct the scope names in the README, the GitHub Action guide and the
  Docker guide, and link them to the new section
@lelia
lelia marked this pull request as ready for review November 14, 2026 02:45
@lelia
lelia requested a review from a team as a code owner November 14, 2026 02:45
@cursor

cursor Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

PR Summary

Low Risk
Documentation-only changes with no runtime or authentication logic modified.

Overview
Documentation now names the least-privilege Socket API scopes (full-scans:create, socket-basics:read) instead of the broader scope groups (full-scans, socket-basics), with cross-links from README.md, docs/github-action.md, and docs/local-install-docker.md to a new canonical section.

docs/parameters.md adds an API token scopes subsection that documents which scopes to grant, how scope groups relate to individual scopes, and which Socket API calls run for dashboard configuration, full-scan upload, and Socket Tier 1 (including endpoints not in the public API reference). It also clarifies behaviors that were easy to misconfigure: missing scopes log warnings/errors but do not change the exit code; on Enterprise, a failed dashboard-config load discards org discovery so uploads need explicit SOCKET_ORG; dashboard config reads only certain API-key env vars; and Tier 1 can use a different token if multiple CLI key variables disagree.

Troubleshooting and configuration-precedence text is aligned everywhere on Enterprise org discovery requiring socket-basics:read when SOCKET_ORG is unset.

Reviewed by Cursor Bugbot for commit be47b1e. Configure here.

@lelia

lelia commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

bugbot run

@lelia lelia added the documentation Improvements or additions to documentation label Nov 14, 2026

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

@flowstate Eric Hibbs (flowstate) left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked the scope table and call flow against the Basics source and the API handlers. The two-scope token is correct and the quoted log strings match. A few accuracy fixes inline, none of which would leave anyone with a non-working token.

On the description: full-scans and socket-basics are valid scopes. They're the parents, and a parent satisfies its children in hasRequiredApiTokenScopes, so the old docs over-granted rather than named something invalid. Related question: socket-basics:read is the only child of socket-basics, and normalizeScopes collapses a full set of children into the parent. Does the dashboard show a token created with socket-basics:read as socket-basics? If so, users may be looking for a name they won't see.

Comment thread docs/github-action.md Resolved
Comment thread docs/parameters.md Resolved
Comment thread docs/parameters.md Resolved
…names

- The organization is discovered from the key without socket-basics:read
  on non-Enterprise plans, where the settings call is never made. Four
  places said discovery always needs the scope.
- POST coana-cli/artifacts checks full-scans:create or fixes:list in its
  handler; it was listed as needing no scope.
- A denied settings call logs one warning, "Error loading Socket Basics
  config: Insufficient permissions", not a separate line before it.
- full-scans and socket-basics are the scope groups, which also work.
  socket-basics:read is the only scope in its group, so the API reports
  it as socket-basics.
- The setup-guide paragraph no longer states which scopes that guide
  lists, since the list is changing.
@lelia

lelia commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, the three inline notes are fixed in be47b1e, with replies on each thread.

On the description: you are right, full-scans and socket-basics are the groups and they work. The description and the docs now say that instead of calling them invalid. The docs still recommend the specific scopes, because full-scans also grants full-scans:list and full-scans:delete.

On the dashboard question: a token created with socket-basics:read is stored as socket-basics, since normalizeScopes runs on create. In the token dialog the socket-basics group shows as checked with socket-basics:read checked under it, so the name is still there to find, and the tokens table has no scopes column. The API tokens list returns socket-basics. docs/parameters.md now says selecting either one is the same token.

@lelia

lelia commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

bugbot run

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ 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 be47b1e. Configure here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants