[lelia]

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 come from the security requirements in the API reference. When an endpoint lists several scopes, all of them are required.
• fullscans.finalize_tier1() and uploadmanifests.upload_manifest_files() call endpoints the reference doesn't list. Both check full-scans:create.
• 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.
• The token parameter under "Initializing the module" links to the new section.

Rows marked "not in the API reference" are deprecated report-era endpoints, plus settings.integration_events(), which calls a path with no GET route. #131 fixes that method. Whichever PR merges second should update its row to GET orgs/{org_slug}/settings/integrations/{integration_id}/events → integration:list and drop it from the "not in the API reference" note.

Some scopes don't match the method name. These are called out in the README:

• 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.

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 mistakes a scope gap for "repository does not exist" because its lookup catches every APIFailure. That's a CLI fix, not an SDK one. 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

• Improve documentation for requisite API token permissions socket-python-cli#353: the same audit for the CLI.
• docs: List the API token scopes Socket Basics needs socket-basics#140: the same audit for Socket Basics.

Public Changelog

Documented the API token scope each SDK method needs.

Fixes: CE-462
Refs: CE-384

[cursor]

PR Summary

Low Risk
README-only documentation update with no runtime, packaging, or security behavior changes.

Overview
Adds an API token scopes section to README.rst so integrators can grant least-privilege tokens without guessing from 403s.

The token parameter note now points to that section. New content explains that each SDK method maps to an HTTP path and the scope(s) the API enforces (including multi-scope requirements), documents how 401/403 surface as APIAccessDenied and related APIFailure subclasses (with a short example), and includes a method → endpoint → scopes table (~85 methods) with callouts for undocumented endpoints, deprecated report-era routes, and scopes that don’t match intuitive method names (e.g. analytics.* → report:write, export.* → report:read).

Documentation only — no SDK or release artifact changes.

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