Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lelia merged 2 commits into from
Jun 26, 2026
+15 −1
Merged

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3bc2da7
docs: document required API token scopes for Socket Basics
dc-larsen Apr 28, 2026
06a5cfc
docs: clarify Socket Basics token scopes
lelia Jun 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ jobs:
> with a review gate. See [docs/github-action.md](docs/github-action.md#pinning-strategies)
> for the full explanation and Dependabot setup.

**That's it!** With just your `SOCKET_SECURITY_API_KEY`, all scanning configurations are managed through the [Socket Dashboard](https://socket.dev/dashboard) — no workflow changes needed.
**That's it!** With a properly scoped `SOCKET_SECURITY_API_KEY`, all scanning configurations are managed through the [Socket Dashboard](https://socket.dev/dashboard) — no workflow changes needed. See [Required API Token Scopes](#required-api-token-scopes) for details.

### What You Get

Expand Down Expand Up @@ -160,6 +160,19 @@ Configure scanning policies, notification channels, and rule sets for your entir

![Socket Basics Section Config](docs/screenshots/socket_basics_section_config.png)

### Required API Token Scopes

Create your `SOCKET_SECURITY_API_KEY` in the [Socket Dashboard](https://socket.dev/dashboard) under **Settings → API Tokens**. Dashboard routes can depend on your organization and login session, so start from the dashboard or see the [Socket API Tokens docs](https://docs.socket.dev/docs/api-keys) for token-management details. Socket Basics needs the following scopes:

| Scope | Required for |
|-------|--------------|
| `full-scans` | Submitting scan results to your organization |
| `socket-basics` | Loading scanner configuration from the Socket Dashboard |

If Socket Basics is configured from the Socket Dashboard, the `socket-basics` scope is required. If it is missing, you will see `Insufficient permissions` when Socket Basics loads dashboard configuration.

If Socket Basics is configured with CLI arguments, environment variables, or a JSON config file, only `full-scans` permissions are required for result submission. Set `SOCKET_ORG` explicitly in your workflow when using this mode.

## 💻 Other Usage Methods

For GitHub Actions, see the [Quick Start](#-quick-start---github-actions) above or the **[Complete GitHub Actions Guide](docs/github-action.md)** for advanced workflows.
Expand Down Expand Up @@ -251,6 +264,7 @@ Add new connectors by:
**Socket API errors:**
- Ensure `SOCKET_SECURITY_API_KEY` and `SOCKET_ORG` are set correctly
- Verify your Socket Enterprise subscription is active
- If you see `Insufficient permissions`, confirm your API token has the scopes required for your configuration mode (see [Required API Token Scopes](#required-api-token-scopes))

**Notifier errors:**
- Check that notification credentials (Slack webhook, Jira token, etc.) are properly configured
Expand Down