docs: List the API token scopes Socket Basics needs

README.md

@@ -154,7 +154,7 @@ Socket Enterprise customers can configure Socket Basics directly from the [Socke
 
 ![Socket Basics Settings](docs/screenshots/socket_basics_settings.png)
 
-Configure scanning policies, notification channels, and rule sets for your entire organization in one place. Socket Basics loads these settings on every run when its API key has the `socket-basics` scope, and they take precedence over the matching workflow inputs, including fields you leave blank. See [Dashboard Settings and Workflow Inputs](docs/github-action.md#dashboard-settings-and-workflow-inputs) for the exceptions and for setting values per repository.
+Configure scanning policies, notification channels, and rule sets for your entire organization in one place. Socket Basics loads these settings on every run when its API key has the `socket-basics:read` scope, and they take precedence over the matching workflow inputs, including fields you leave blank. See [Dashboard Settings and Workflow Inputs](docs/github-action.md#dashboard-settings-and-workflow-inputs) for the exceptions and for setting values per repository.
 
 ![Socket Basics Section Config](docs/screenshots/socket_basics_section_config.png)
 
@@ -164,12 +164,14 @@ Create your `SOCKET_SECURITY_API_KEY` in the [Socket Dashboard](https://socket.d
 
 | Scope | Required for |
 |-------|--------------|
-| `full-scans` | Submitting scan results to your organization |
-| `socket-basics` | Loading scanner configuration from the Socket Dashboard |
+| `full-scans:create` | Submitting scan results to your organization, and running Socket Tier 1 reachability |
+| `socket-basics:read` | Loading scanner configuration from the Socket Dashboard (Enterprise organizations) |
 
-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 from the Socket Dashboard, `socket-basics:read` is required. If it is missing, the log shows `Insufficient permissions` and `Error loading Socket Basics config`, and the scan runs with the workflow inputs alone. On an Enterprise organization the organization is then not discovered from the key either, so results are not uploaded unless `SOCKET_ORG` is set.
 
-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.
+If Socket Basics is configured with CLI arguments, environment variables, or a JSON config file, only `full-scans:create` is required. Set `SOCKET_ORG` explicitly in your workflow when using this mode.
+
+A missing scope does not change the exit code. See [API token scopes](docs/parameters.md#api-token-scopes) for every Socket API call Socket Basics makes and the scope each one checks.
 
 ## 💻 Other Usage Methods
 
@@ -270,7 +272,7 @@ Add new connectors by:
 
 **Socket API errors / results missing from the dashboard:**
 - Ensure `SOCKET_SECURITY_API_KEY` and `SOCKET_ORG` are set correctly
-- `No Socket organization configured` in the log means nothing was uploaded: set `SOCKET_ORG`, or use a key with the `socket-basics` scope so the organization can be discovered
+- `No Socket organization configured` in the log means nothing was uploaded: set `SOCKET_ORG`, or use a key with the `socket-basics:read` scope so the organization can be discovered
 - `Need at least one file to be uploaded` means the facts file was written outside the scanned workspace; keep `--output` inside it (see [Save Results to File](docs/local-install-docker.md#save-results-to-file))
 - 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))

docs/github-action.md

@@ -210,7 +210,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 - Without it the scan still runs and comments on the PR, but nothing reaches the Socket dashboard.
 
 **`socket_org`** (optional)
-- Discovered from the API key when the key has the `socket-basics` scope. Set it
+- Discovered from the API key when the key has the `socket-basics:read` scope. Set it
   explicitly when configuring the scan from `with:` inputs instead of the dashboard.
 - Outside the action the same value is `SOCKET_ORG` or `--socket-org`. See the
   [name mapping](parameters.md#name-mapping) for the equivalents of every input.
@@ -498,7 +498,7 @@ The dashboard configuration loads when all three of these are true:
 
 - The organization is on a Socket Enterprise plan.
 - Socket Basics is enabled for the organization.
-- The API key has the `socket-basics` scope.
+- The API key has the `socket-basics:read` scope.
 
 Fields you leave blank in the dashboard still count. The dashboard sends a blank
 field as an empty value and a switched-off toggle as `false`, and either one
@@ -1112,11 +1112,12 @@ env:
 **Solutions:**
 1. Provide `socket_security_api_key`. Without it the scan runs locally only.
 2. Check the log for `No Socket organization configured`. Either set `socket_org`
-   or use an API key with the `socket-basics` scope so the organization can be
-   discovered from the key.
-3. Check the token scopes: `full-scans` is required to upload;
-   `socket-basics` is required to load dashboard configuration. `Insufficient
-   permissions` in the log means a scope is missing.
+   or use an API key with the `socket-basics:read` scope so the organization can
+   be discovered from the key.
+3. Check the token scopes: `full-scans:create` is required to upload;
+   `socket-basics:read` is required to load dashboard configuration.
+   `Insufficient permissions` in the log means a scope is missing. See
+   [API token scopes](parameters.md#api-token-scopes).
 4. `pr_comment_enabled: 'false'` does **not** affect the upload; results still
    reach the dashboard.
 

docs/local-install-docker.md

@@ -785,12 +785,13 @@ security-scan:
 1. `Need at least one file to be uploaded` in the log: the facts file was
    written outside the workspace. Use a path under `/workspace` for `--output`.
 2. `No Socket organization configured` in the log: set `SOCKET_ORG`, or use an
-   API key with the `socket-basics` scope so the organization can be discovered.
+   API key with the `socket-basics:read` scope so the organization can be discovered.
 3. `Socket API key not detected - running in free plan mode`: the key did not
    reach the container. Check the `.env` file or `-e` flags and the variable
    name (`SOCKET_SECURITY_API_KEY`).
-4. `Insufficient permissions`: the key is missing the `full-scans` scope (upload)
-   or the `socket-basics` scope (dashboard configuration).
+4. `Insufficient permissions`: the key is missing the `full-scans:create` scope
+   (upload) or the `socket-basics:read` scope (dashboard configuration). See
+   [API token scopes](parameters.md#api-token-scopes).
 
 ### PR Comment Not Posted
 

docs/parameters.md

@@ -37,7 +37,7 @@ GitHub Action input is delivered to the container as the environment variable
 | `--console-tabular-enabled` | `console_tabular_enabled` | `INPUT_CONSOLE_TABULAR_ENABLED` | `console_tabular_enabled` | Print consolidated findings as tables. |
 | `--console-json-enabled` | `console_json_enabled` | `INPUT_CONSOLE_JSON_ENABLED` | `console_json_enabled` | Print consolidated findings as JSON. |
 | `--socket-org` | `socket_org` | `SOCKET_ORG` (also `SOCKET_ORG_SLUG`, `INPUT_SOCKET_ORG`) | `socket_org` | Socket organization slug. Not the same thing as `--repo`. |
-| —<sup>2</sup> | `socket_security_api_key` | `SOCKET_SECURITY_API_KEY` (also `SOCKET_SECURITY_API_TOKEN`, `SOCKET_API_KEY`, `INPUT_SOCKET_SECURITY_API_KEY`) | `socket_api_key`<sup>3</sup> | Socket API key (`full-scans` scope to upload, `socket-basics` scope to load dashboard config). |
+| —<sup>2</sup> | `socket_security_api_key` | `SOCKET_SECURITY_API_KEY` (also `SOCKET_SECURITY_API_TOKEN`, `SOCKET_API_KEY`, `INPUT_SOCKET_SECURITY_API_KEY`) | `socket_api_key`<sup>3</sup> | Socket API key (`full-scans:create` scope to upload, `socket-basics:read` scope to load dashboard config; see [API token scopes](#api-token-scopes)). |
 | `--repo` | — | `GITHUB_REPOSITORY` | `repo` | `owner/repo` recorded on the scan and used to find the PR. Discovered from git when omitted. |
 | `--branch` | — | `GITHUB_HEAD_REF`, `GITHUB_REF_NAME` | `branch` | Branch recorded on the scan. Discovered from git when omitted. |
 | `--pull-request` | — | `GITHUB_PR_NUMBER` (also `INPUT_PR_NUMBER`) | — | PR number. The PR notifier reads the environment variable. |
@@ -701,12 +701,110 @@ export SOCKET_SECURITY_API_KEY="scrt_..."
 socket-basics --socket-org your-org-slug --python --secrets
 ```
 
-The key needs the `full-scans` scope to upload results and the `socket-basics`
-scope to load dashboard configuration. With the latter the organization is
-discovered from the key; otherwise set `SOCKET_ORG` explicitly or the run logs
+The key needs `full-scans:create` to upload results and `socket-basics:read`
+to load dashboard configuration; see [API token scopes](#api-token-scopes).
+When `SOCKET_ORG` is not set, the organization is discovered from the key. On
+an Enterprise organization that discovery is lost if the key lacks
+`socket-basics:read`, so set `SOCKET_ORG` explicitly or the run logs
 `No Socket organization configured` and uploads nothing. `--repo` names the
 repository, not the organization.
 
+### API token scopes
+
+Socket Basics authenticates with a single Socket organization API token. A
+token missing a scope does **not** fail the run. Each Socket API call that is
+denied logs an error or a warning and the scan continues, so check the log
+rather than the exit code.
+
+#### Scopes to grant
+
+For a least-privilege token, grant these:
+
+| Scope | Needed for |
+|:---|:---|
+| `full-scans:create` | Uploading results to the Socket dashboard. Socket Tier 1 also needs it to upload manifests and record the reachability scan |
+| `socket-basics:read` | Loading scanner configuration from the Socket dashboard, on Enterprise organizations. Without it on an Enterprise organization, the organization is also not discovered from the key |
+
+The scopes each endpoint checks are listed in the
+[API reference](https://docs.socket.dev/reference). A few calls check no scope
+and work with any valid token for the organization: `GET organizations` and
+`GET orgs/{org}/supported-files`.
+
+Socket Basics does not use the `repo:*`, `full-scans:list`, `diff-scans:*`,
+`packages:list`, `security-policy:read` or `triage:*` scopes. It never looks up
+or creates the repository with a separate call. The repository name travels as
+a parameter of the scan upload.
+
+The [CI/CD token setup guide](https://docs.socket.dev/docs/create-socket-api-key-for-cicd)
+is written for the Socket CLIs. Its list includes `full-scans:create`, so a
+token made from it can upload results, but it does not include
+`socket-basics:read`. Add that scope to load dashboard configuration.
+
+#### API calls by run type
+
+**Dashboard configuration**, at startup on every run where the key is set and
+no `--config` file is given:
+
+| API call | Scope | Purpose |
+|:---|:---|:---|
+| `GET organizations` | none | Find the organization (the one named by `SOCKET_ORG`, or the first one the key belongs to) and its plan |
+| `GET orgs/{org}/settings/socket-basics` | `socket-basics:read` | Load the dashboard configuration. **Only called when the plan is Enterprise** |
+
+This step reads the key from `SOCKET_SECURITY_API_KEY`,
+`SOCKET_SECURITY_API_TOKEN` or `INPUT_SOCKET_SECURITY_API_KEY` only. A key set
+only as `SOCKET_API_KEY` or `INPUT_SOCKET_API_KEY` is used for uploads and
+Tier 1 but skips this step.
+
+If either call fails, the log shows `Error loading Socket Basics config` and
+the run continues with the environment and workflow inputs alone. Nothing from
+this step is kept, including the discovered organization, so set `SOCKET_ORG`
+when the key lacks `socket-basics:read`. When the settings call is denied for a
+missing scope, the error logged just before it starts with
+`Insufficient permissions`.
+
+**Result upload**, after the scanners finish:
+
+| API call | Scope | Purpose |
+|:---|:---|:---|
+| `POST orgs/{org}/full-scans` | `full-scans:create` | Upload `.socket.facts.json` as a full scan |
+
+The upload is skipped, without calling the API, when the facts file has no
+components, when no key or organization is configured, or when
+`SKIP_SOCKET_SUBMISSION=1`. If the repository does not exist in Socket yet, the
+upload creates it, and an organization API token needs no scope beyond
+`full-scans:create` for that. A denied upload logs
+`Failed to submit socket facts file` and does not change the exit code.
+
+**Socket Tier 1** (`--socket-tier1`), unless `SKIP_SOCKET_REACH=1`. Socket
+Basics runs the Socket npm CLI (`socket scan reach --org <org>`), which makes
+these calls with the same token:
+
+| API call | Scope | Purpose |
+|:---|:---|:---|
+| `GET organizations` | none | Check that the organization is on an Enterprise plan |
+| `GET orgs/{org}/supported-files` | none | Fetch the supported manifest file patterns |
+| `POST orgs/{org}/coana-cli/artifacts` | none | Find the reachability engine download. Only called when the engine is not cached, which is every run in a fresh container (see [Network access for Tier 1](#network-access-for-tier-1)) |
+| `POST orgs/{org}/upload-manifest-files` | `full-scans:create` | Upload the manifests for analysis |
+| `POST tier1-reachability-scan/finalize` | `full-scans:create` | Mark the reachability scan done. A failure here only logs a warning |
+
+The reachability engine (Coana) runs with the same token, and its calls check
+`full-scans:create`. The `coana-cli/artifacts`, `upload-manifest-files` and
+`tier1-reachability-scan/finalize` endpoints are not in the public API
+reference. Options passed through
+`socket_additional_params` can make further calls that this table does not
+cover.
+
+A Tier 1 failure logs `Error running connector socket_tier1` and does not
+change the exit code. Tier 1 passes the key to the Socket npm CLI as
+`SOCKET_SECURITY_API_KEY`, but that CLI prefers `SOCKET_CLI_API_TOKEN`,
+`SOCKET_CLI_API_KEY` or `SOCKET_SECURITY_API_TOKEN` when one of them is set in
+the environment. If you set more than one of these, give them the same token.
+
+The heavy image's Python CLI (`socketcli`) is a separate tool that Socket
+Basics does not run. For the scopes it needs, see
+[API token permissions](https://github.com/SocketDev/socket-python-cli/blob/main/docs/troubleshooting.md#api-token-permissions)
+in its documentation.
+
 ### `--socket-tier1`
 Enable Socket Tier 1 reachability analysis for dependency scanning.
 
@@ -1021,7 +1119,7 @@ Configuration is merged in the following order (later sources override earlier o
 
 1. Default values
 2. Environment variables, including GitHub Action inputs (the action passes each `with:` input as an `INPUT_*` variable)
-3. Socket Basics dashboard configuration (when the organization is on an Enterprise plan with Socket Basics enabled, the API key has the `socket-basics` scope, and no `--config` file is used)
+3. Socket Basics dashboard configuration (when the organization is on an Enterprise plan with Socket Basics enabled, the API key has the `socket-basics:read` scope, and no `--config` file is used)
 4. JSON configuration file (via `--config`)
 5. Command-line arguments