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

Open
David Larsen (dc-larsen) wants to merge 1 commit into
base: main
Choose a base branch
from
+12 −0
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
12 changes: 12 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,17 @@ 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 under **Settings → API Tokens**. Socket Basics needs the following scopes:
Copy link
Copy Markdown
Contributor

@lelia lelia Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?


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

If your token is missing the `socket-basics` scope, you will see `Insufficient permissions` when Socket Basics tries to load dashboard config. As a workaround, set `SOCKET_ORG` explicitly in your workflow to skip the dashboard config load and run with CLI/environment configuration only.
Copy link
Copy Markdown

@bergenhem Carl Bergenhem (bergenhem) Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## 💻 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 +262,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 `socket-basics` and `full-scans` scopes (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