Repository navigation
Document the API token scopes each SDK method needs - #130
Conversation
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.
PR SummaryLow Risk Overview The new content explains how scope groups and repository-scoped tokens interact with checks, how 401/403 map to Footnotes call out non-obvious scope names (e.g. Reviewed by Cursor Bugbot for commit be87415. Configure here. |
|
bugbot run |
Eric Hibbs (flowstate)
left a comment
There was a problem hiding this comment.
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.
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.
|
Thanks, all four inline notes are addressed in be87415, with replies on each thread. Re-reading the handlers turned up one more row: The README also gained two short paragraphs: scope groups ( |
|
bugbot run |
There was a problem hiding this comment.
✅ 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.
Eric Hibbs (flowstate)
left a comment
There was a problem hiding this comment.
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.
Adds an "API token scopes" section to
README.rstso callers can provision a token for the methods they use, without trial and error against 403s.report.view()callsGET report/view/{id}, which the reference says will be removed on 2026-11-20.fullscans.finalize_tier1(),uploadmanifests.upload_manifest_files()andsbom.view()call endpoints the reference doesn't list. Their scopes are in the table.APIAccessDeniedwithstatus_code403 and the server'sInsufficient permissionsmessage. Every method raises rather than returning{}, becausedo_request()raises before the method sees the response. CatchingAPIFailurecovers every case.full-scanscoversfull-scans:*) and of tokens restricted to specific repositories, which some endpoints reject whatever scopes they hold.tokenparameter under "Initializing the module" links to the new section.Things the table surfaces
apitokens.update(token_id=...),dependencies.get()with all four arguments, andrepositories.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.APIInsufficientPermissionsandAPIOrganizationNotAllowedmatch 403 messages the API doesn't currently send. The README says to catchAPIAccessDeniedfor a missing scope.dependencies.get()anddependencies:list.POST dependencies/searchchecks no scope at the route, but filters results by the token'sdependencies:listrepository access. Depending on how the organization restricts repository access, a token without it gets an empty result instead of a 403.analytics.get_org()andanalytics.get_repo()checkreport:write.apitokens.update()checksapi-tokens:create.labels.setting.delete()checksrepo-label:update. Theexport.*_bom()methods checkreport:read.Merge order
The
settings.integration_events()row gives the/eventspath andintegration:list, which is what the method does once #131 lands. Merge #131 first.README only, so no version bump.
version-checkenforces a bump only for changes undersocketdev/,pyproject.tomloruv.lock. The README renders cleanly withreadme_renderer, which is whattwine checkuses.Questions this answers
GET organizations,GET report/supportedandPOST license-metadatacheck no scope, so any valid token works.export.cdx_bom()and the other exports checkreport:read. The manifest upload andfinalize_tier1()checkfull-scans:create.APIAccessDeniedwithstatus_code403, not a bareAPIFailure. socket-python-cli used to mistake a scope gap for "repository does not exist" because its lookup caught everyAPIFailure. That was a CLI issue, fixed in socket-python-cli 2.13.0. Recent API responses also name the required scopes inerror.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
settings.integration_events()to request the events path #131: fixessettings.integration_events(). Merge it before this one.Public Changelog
Documented the API token scope each SDK method needs.
Fixes: CE-462
Refs: CE-384