Skip to content

Document the API token scopes each SDK method needs - #130

Merged
lelia merged 4 commits into
mainfrom
lelia/api-token-scope-docs
Nov 20, 2026
Merged

lelia merged 4 commits into
mainfrom
lelia/api-token-scope-docs

Conversation

@lelia

@lelia lelia commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Adds an "API token scopes" section to README.rst so callers can provision a token for the methods they use, without trial and error against 403s.

  • A table of every SDK method that makes a request, with the endpoint it calls and the scope that endpoint checks: 85 methods, 89 rows, since four methods can call more than one endpoint. Scopes are the ones each route handler checks, which the API reference also lists. When an endpoint lists several scopes, all of them are required.
  • Endpoints the API reference lists as deprecated are marked "Deprecated". report.view() calls GET report/view/{id}, which the reference says will be removed on 2026-11-20.
  • fullscans.finalize_tier1(), uploadmanifests.upload_manifest_files() and sbom.view() call endpoints the reference doesn't list. Their scopes are in the table.
  • A subsection on what a 401 or 403 raises. A missing scope raises APIAccessDenied with status_code 403 and the server's Insufficient permissions message. Every method raises rather than returning {}, because do_request() raises before the method sees the response. Catching APIFailure covers every case.
  • A short explanation of scope groups (full-scans covers full-scans:*) and of tokens restricted to specific repositories, which some endpoints reject whatever scopes they hold.
  • The token parameter under "Initializing the module" links to the new section.

Things the table surfaces

  • Three calls can't succeed. apitokens.update(token_id=...), dependencies.get() with all four arguments, and repositories.list() request paths the API has no route for, so they return a 404 whatever the token. The README says so and points to the working alternative. Fixing or removing them is a code change, left for a follow-up.
  • Two exception classes aren't raised today. APIInsufficientPermissions and APIOrganizationNotAllowed match 403 messages the API doesn't currently send. The README says to catch APIAccessDenied for a missing scope.
  • dependencies.get() and dependencies:list. POST dependencies/search checks no scope at the route, but filters results by the token's dependencies:list repository access. Depending on how the organization restricts repository access, a token without it gets an empty result instead of a 403.
  • Scopes that don't match the method name. analytics.get_org() and analytics.get_repo() check report:write. apitokens.update() checks api-tokens:create. labels.setting.delete() checks repo-label:update. The export.*_bom() methods check report:read.

Merge order

The settings.integration_events() row gives the /events path and integration:list, which is what the method does once #131 lands. Merge #131 first.

README only, so no version bump. version-check enforces a bump only for changes under socketdev/, pyproject.toml or uv.lock. The README renders cleanly with readme_renderer, which is what twine check uses.

Questions this answers

  • Calls with no published scope. GET organizations, GET report/supported and POST license-metadata check no scope, so any valid token works. export.cdx_bom() and the other exports check report:read. The manifest upload and finalize_tier1() check full-scans:create.
  • Does a scope gap need a clearer SDK error? It already gets one. A missing scope raises APIAccessDenied with status_code 403, not a bare APIFailure. socket-python-cli used to mistake a scope gap for "repository does not exist" because its lookup caught every APIFailure. That was a CLI issue, fixed in socket-python-cli 2.13.0. Recent API responses also name the required scopes in error.details.requiredScopes, which the SDK leaves out of the exception message. Surfacing them would be a small follow-up.

Not in this PR

The Socket Python SDK page on docs.socket.dev still says nothing about scopes, and doesn't cover diffscans. This PR covers the README, which is what PyPI shows. The docs-site page needs its own change in SocketDev/docs.

Related PRs

Public Changelog

Documented the API token scope each SDK method needs.

Fixes: CE-462
Refs: CE-384

Add an "API token scopes" section to the README that maps every SDK
method to the endpoint it calls and the scopes that endpoint checks,
matching the per-endpoint scopes in the public API reference.

It also explains how a 401 or 403 surfaces: a missing scope raises
APIAccessDenied with status_code 403 and the server's "Insufficient
permissions" message, and 403s with more specific messages raise
APIInsufficientPermissions, APIOrganizationNotAllowed or
APIInsufficientQuota, all subclasses of APIFailure.

Methods whose endpoint the reference does not list are marked as such
rather than given a guessed scope.
@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 README change; no runtime or dependency behavior changes.

Overview
Adds an API token scopes section to README.rst so integrations can grant least-privilege tokens without guessing from 403s. The token init parameter now links to that section.

The new content explains how scope groups and repository-scoped tokens interact with checks, how 401/403 map to APIAccessDenied, APIInsufficientQuota, and related APIFailure subclasses (with a short handling example), and includes a scopes-by-method table (~85 methods) mapping each call to its HTTP path and required scopes—including deprecated routes, undocumented endpoints, and three SDK calls documented as always 404.

Footnotes call out non-obvious scope names (e.g. export.* → report:read), dependencies.get() vs dependencies:list, and known broken call patterns left for follow-up code fixes.

Reviewed by Cursor Bugbot for commit be87415. Configure here.

@lelia

lelia commented Nov 14, 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.

Stale Bugbot comment from a previous run.

@flowstate Eric Hibbs (flowstate) left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Checked the table against socketdev/ and the api-v0 route handlers: every request-making method is listed, and 84 of the 89 rows match on method, path and scope. The rest are the rows marked "not in the API reference", plus two exception bullets. Notes inline.

Comment thread README.rst Resolved
Comment thread README.rst Resolved
Comment thread README.rst Resolved
Comment thread README.rst Resolved
Checked against the API's route handlers:

- Three calls request a path with no route and always fail with a 404:
  apitokens.update(token_id=...), dependencies.get() with all four
  arguments, and repositories.list(). They were marked "not in the API
  reference", which read as working but undocumented.
- sbom.view() checks report:read.
- settings.integration_events() is listed with the /events path and
  integration:list.
- POST dependencies/search checks no scope at the route but filters
  results by dependencies:list repository access.
- The API sends neither "Insufficient permissions for API method" nor
  "Organization not allowed", so APIInsufficientPermissions and
  APIOrganizationNotAllowed are not raised today. A missing scope is
  APIAccessDenied.

Also marks the endpoints the API reference lists as deprecated, and
explains scope groups and tokens restricted to specific repositories.
@lelia

lelia commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, all four inline notes are addressed in be87415, with replies on each thread.

Re-reading the handlers turned up one more row: dependencies.get() calls POST dependencies/search, which checks no scope at the route but filters results by the token's dependencies:list repository access. Depending on how the organization restricts repository access, a token without it gets an empty result instead of a 403. The row and a note now say so.

The README also gained two short paragraphs: scope groups (full-scans covers full-scans:*, and a full set of scopes is stored as the group name), and tokens restricted to specific repositories, which some endpoints reject whatever scopes they hold.

@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 be87415. Configure here.

@flowstate Eric Hibbs (flowstate) left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Re-checked be87415 against the api-v0 routes and spec: the no-route rows, sbom.view(), the exception section and all 17 deprecated markers match.

@lelia
lelia merged commit 38d201b into main Nov 20, 2026
14 checks passed
@lelia
lelia deleted the lelia/api-token-scope-docs branch November 20, 2026 22:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants