Skip to content

docs: document required API token scopes for Socket Basics#68

Merged
lelia merged 2 commits into
mainfrom
docs/api-token-scopes
Jun 26, 2026
Merged

docs: document required API token scopes for Socket Basics#68
lelia merged 2 commits into
mainfrom
docs/api-token-scopes

Conversation

@dc-larsen

Copy link
Copy Markdown
Contributor

Summary

Document the minimum Socket API token scopes required for Socket Basics. Customers consistently hit Insufficient permissions errors when their token is missing the socket-basics scope, and there's no current guidance in the README on which scopes to grant when creating a token.

What scopes does Socket Basics actually need?

Verified against api.socket.dev/v0 by testing each endpoint Socket Basics calls with tokens of varying scope:

Token scopes sdk.org.get() sdk.basics.get_config() sdk.fullscans.post()
socket-basics only works works fails (Insufficient permissions)
socket-basics + full-scans works works works
full-scans + repo works fails works
socket-basics + full-scans + repo works works works

The repo scope is not needed — /full-scans creates the repo implicitly when the named repo doesn't exist yet.

Changes

  • New "Required API Token Scopes" subsection under Enterprise Dashboard Configuration listing the two required scopes and their purpose.
  • Updated Troubleshooting → Socket API errors to point readers at the new section when they see Insufficient permissions.

Test plan

  • Verified scope requirements by creating test tokens with each scope combination and exercising every endpoint Socket Basics calls (sdk.org.get, sdk.basics.get_config, sdk.fullscans.post).
  • Markdown table renders correctly in GitHub preview.
  • Anchor link #required-api-token-scopes resolves.

@dc-larsen David Larsen (dc-larsen) requested a review from a team as a code owner April 28, 2026 03:54
Comment thread README.md Outdated
Comment thread README.md Outdated
@lelia lelia merged commit e8d52a6 into main Jun 26, 2026
10 checks passed
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.

3 participants