docs: document required API token scopes for Socket Basics

[David Larsen (dc-larsen)]

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.

[Carl Bergenhem (bergenhem)]

"tries to load dashboard config", and why this workaround is needed is not super clear. We can probably highlight the breakdown a bit differently. Maybe something like this? Or, alternatively, should we just say that socket-basics is needed no matter what to simplify things?

---

If the Socket dashboard has been used to configure Socket Basics the socket-basics scope is required. If missing, a Insufficient permissions error will occur.

If Socket Basics is configured via CLI or environment files, only full-scans permissions are required. Note, this does require setting the SOCKET_ORG field appropriately.

[lelia]

Is there a shortcut link we can include that takes customers directly to the API creation page for convenience? or will this not work as the URI would be org-slug-specific?