Skip to content
Merged
Changes from all commits
Commits
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
376 changes: 375 additions & 1 deletion README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Initializing the module

**PARAMETERS:**

- **token (str)** - The Socket API Key for your Organization
- **token (str)** - The Socket API Key for your Organization. Each method needs the token to carry particular scopes; see `API token scopes`_
- **timeout (int)** - The number of seconds to wait before failing the connection
- **allow_unverified (bool)** - Whether to skip SSL certificate verification (default: False). Set to True for testing with self-signed certificates.
- **user_agent (str, optional)** - Custom User-Agent string to use in API requests. If not provided, defaults to "SocketSDKPython/{version}"
Expand Down Expand Up @@ -1498,3 +1498,377 @@ List historical snapshots for an organization.

- **org_slug (str)** - The organization slug
- **query_params (dict, optional)** - Optional query parameters for filtering


API token scopes
----------------

The SDK authenticates every call with one organization API token, and each Socket API
endpoint checks that the token carries particular scopes. The table below lists, for each
SDK method, the endpoint it calls and the scopes that endpoint checks. Where an endpoint
lists more than one scope, the token needs all of them. "none" means the endpoint checks
no scope, so any valid token for the organization works. Paths are relative to
``https://api.socket.dev/v0/``; query strings are omitted.

The scopes each endpoint checks are also listed in the
`API reference <https://docs.socket.dev/reference>`_. For a least-privilege token, grant
only the scopes of the methods your integration calls.

Scopes are grouped by their prefix, and a token that holds a group holds every scope in
it: ``full-scans`` covers ``full-scans:list``, ``full-scans:create`` and
``full-scans:delete``. When a token is given every scope of a group, the API stores and
reports the group name instead, so a token created with ``packages:list``, the only
scope in its group, is listed with ``packages``.

Scopes are not the only check. A token restricted to specific repositories is rejected
by some endpoints whatever scopes it holds, and organizations that restrict repository
access apply per-repository checks on top of the scopes listed here.

Missing scopes and other 403 responses
""""""""""""""""""""""""""""""""""""""

Methods do not return an empty result on a 401 or 403. ``API.do_request()`` raises
before the method sees the response, so the exception reaches the caller, including when
``use_types=True``.

A missing scope raises ``APIAccessDenied`` with ``status_code`` 403. Its message starts
with the server's ``Insufficient permissions``, followed by the request URL and the
response headers. A 401, from a bad or revoked token, also raises ``APIAccessDenied``,
with ``Unauthorized`` in the message.

Recent API responses name the required scopes in the 403 body under
``error.details.requiredScopes``, but the SDK does not include them in the exception
message; to see them, look up the endpoint in the table below or the API reference.

A token restricted to specific repositories gets the same exception from an endpoint
that does not accept such tokens. Its message starts with ``This endpoint does not
support repository-scoped tokens``.

A 403 whose message contains ``Insufficient max quota`` raises ``APIInsufficientQuota``
instead, as does a 429, and logs the server's message at ``ERROR`` on the ``socketdev``
logger.

``socketdev.exceptions`` also defines ``APIInsufficientPermissions`` and
``APIOrganizationNotAllowed``. The SDK raises them for 403 messages containing
``Insufficient permissions for API method`` and ``Organization not allowed``, which the
API does not currently send. Do not rely on either to detect a missing scope: catch
``APIAccessDenied``.

All of these classes carry the HTTP status in ``status_code`` and subclass
``APIFailure``, so catching ``APIFailure`` covers every case.

.. code-block:: python

from socketdev import socketdev
from socketdev.exceptions import APIAccessDenied

socket = socketdev(token="REPLACE_ME")
try:
socket.diffscans.list("org_slug")
except APIAccessDenied as error:
if error.status_code == 403:
print("Access denied; check the token's scopes for this method:", error)
raise

Scopes by method
""""""""""""""""

A few rows need a note:

- "Deprecated" marks an endpoint the API reference lists as deprecated. Prefer the
method the reference names as its successor. ``report.view()`` calls
``GET report/view/{id}``, which the reference says will be removed on 2026-11-20;
use ``fullscans`` instead.
- ``fullscans.finalize_tier1()``, ``uploadmanifests.upload_manifest_files()`` and
``sbom.view()`` call endpoints the API reference does not list. Their scopes are
given in the table.
- Three calls request a path the API has no route for, so they fail with a 404
(``APIResourceNotFound``) whatever the token: ``apitokens.update()`` when
``token_id`` is passed, ``dependencies.get()`` when ``org_slug``, ``ecosystem``,
``package`` and ``version`` are all passed, and ``repositories.list()``. Call
``apitokens.update()`` without ``token_id``, and use ``repos.get()`` to list
repositories.
- ``dependencies.get()`` otherwise calls ``POST dependencies/search``. That endpoint
accepts any valid token, but it returns only results from repositories the token can
read under ``dependencies:list``. Depending on how the organization restricts
repository access, a token without that scope gets an empty result instead of a 403,
so grant ``dependencies:list``.
- Some scopes differ from what the method name suggests: ``analytics.get_org()`` and
``analytics.get_repo()`` check ``report:write``; ``apitokens.update()`` checks
``api-tokens:create``; ``labels.setting.delete()`` checks ``repo-label:update``; and
the ``export`` methods check ``report:read`` rather than a full-scans scope.

.. list-table::
:header-rows: 1
:widths: 30 45 25

* - Method
- Endpoint
- Scopes
* - ``alertfullscansearch.search()``
- ``GET orgs/{org_slug}/alert-full-scan-search``
- ``alerts:list``
* - ``alerts.get()``
- ``GET orgs/{org_slug}/alerts``
- ``alerts:list``
* - ``alerttypes.get()``
- ``POST alert-types``
- none
* - ``analytics.get_org()``
- ``GET analytics/org/{filter}``. Deprecated
- ``report:write``
* - ``analytics.get_repo()``
- ``GET analytics/repo/{name}/{filter}``. Deprecated
- ``report:write``
* - ``apitokens.create()``
- ``POST orgs/{org_slug}/api-tokens``
- ``api-tokens:create``
* - ``apitokens.list()``
- ``GET orgs/{org_slug}/api-tokens``
- ``api-tokens:list``
* - ``apitokens.update()``
- ``POST orgs/{org_slug}/api-tokens/update``
- ``api-tokens:create``
* - ``apitokens.update(token_id=...)``
- ``PUT orgs/{org_slug}/api-tokens/{token_id}``
- no such route; the call fails
* - ``apitokens.rotate()``
- ``POST orgs/{org_slug}/api-tokens/rotate``
- ``api-tokens:rotate``
* - ``apitokens.revoke()``
- ``POST orgs/{org_slug}/api-tokens/revoke``
- ``api-tokens:revoke``
* - ``auditlog.get()``
- ``GET orgs/{org_slug}/audit-log``
- ``audit-log:list``
* - ``basics.get_config()``
- ``GET orgs/{org_slug}/settings/socket-basics``
- ``socket-basics:read``
* - ``dependencies.post()``
- ``POST dependencies/upload``. Deprecated
- ``report:write``
* - ``dependencies.get()``
- ``POST dependencies/search``
- none; ``dependencies:list`` to get results (see the note above)
* - ``dependencies.get(org_slug, ecosystem, package, version)``
- ``GET orgs/{org_slug}/dependencies/{ecosystem}/{package}/{version}``
- no such route; the call fails
* - ``diffscans.list()``
- ``GET orgs/{org_slug}/diff-scans``
- ``diff-scans:list``
* - ``diffscans.get()``
- ``GET orgs/{org_slug}/diff-scans/{diff_scan_id}``
- ``diff-scans:list``
* - ``diffscans.create_from_repo()``
- ``POST orgs/{org_slug}/diff-scans/from-repo/{repo_slug}``
- ``diff-scans:create``, ``full-scans:create`` and ``repo:list``
* - ``diffscans.create_from_ids()``
- ``POST orgs/{org_slug}/diff-scans/from-ids``
- ``diff-scans:create`` and ``full-scans:list``
* - ``diffscans.gfm()``
- ``GET orgs/{org_slug}/diff-scans/{diff_scan_id}/gfm``. Deprecated
- ``diff-scans:list``
* - ``diffscans.delete()``
- ``DELETE orgs/{org_slug}/diff-scans/{diff_scan_id}``
- ``diff-scans:delete``
* - ``export.cdx_bom()``
- ``GET orgs/{org_slug}/export/cdx/{id}``
- ``report:read``
* - ``export.spdx_bom()``
- ``GET orgs/{org_slug}/export/spdx/{id}``
- ``report:read``
* - ``export.openvex_bom()``
- ``GET orgs/{org_slug}/export/openvex/{id}``
- ``report:read``
* - ``fixes.get()``
- ``GET orgs/{org_slug}/fixes``. Deprecated
- ``fixes:list``
* - ``fullscans.get()``
- ``GET orgs/{org_slug}/full-scans``, or ``GET orgs/{org_slug}/full-scans/{full_scan_id}`` when ``params`` holds only ``id``
- ``full-scans:list``
* - ``fullscans.post()``
- ``POST orgs/{org_slug}/full-scans``
- ``full-scans:create``
* - ``fullscans.delete()``
- ``DELETE orgs/{org_slug}/full-scans/{full_scan_id}``
- ``full-scans:delete``
* - ``fullscans.stream_diff()``
- ``GET orgs/{org_slug}/full-scans/diff``. Deprecated
- ``full-scans:list``
* - ``fullscans.stream()``
- ``GET orgs/{org_slug}/full-scans/{full_scan_id}``
- ``full-scans:list``
* - ``fullscans.metadata()``
- ``GET orgs/{org_slug}/full-scans/{full_scan_id}/metadata``
- ``full-scans:list``
* - ``fullscans.gfm()``
- ``GET orgs/{org_slug}/full-scans/diff/gfm``. Deprecated
- ``full-scans:list``
* - ``fullscans.finalize_tier1()``
- ``POST tier1-reachability-scan/finalize``
- ``full-scans:create`` (not in the API reference)
* - ``fullscans.archive()``
- ``POST orgs/{org_slug}/full-scans/archive``
- ``full-scans:create``
* - ``fullscans.rescan()``
- ``POST orgs/{org_slug}/full-scans/{full_scan_id}/rescan``
- ``full-scans:create``
* - ``fullscans.get_tar_files()``
- ``GET orgs/{org_slug}/full-scans/{full_scan_id}/files/tar``
- ``full-scans:list``
* - ``historical.list()``
- ``GET orgs/{org_slug}/historical/alerts``
- ``historical:alerts-list``
* - ``historical.trend()``
- ``GET orgs/{org_slug}/historical/alerts/trend``
- ``historical:alerts-trend``
* - ``historical.dependencies_trend()``
- ``GET orgs/{org_slug}/historical/dependencies/trend``
- ``historical:dependencies-trend``
* - ``historical.snapshots.create()``
- ``POST orgs/{org_slug}/historical/snapshots``
- ``historical:snapshots-start``
* - ``historical.snapshots.list()``
- ``GET orgs/{org_slug}/historical/snapshots``
- ``historical:snapshots-list``
* - ``labels.list()``
- ``GET orgs/{org_slug}/repos/labels``
- ``repo-label:list``
* - ``labels.post()``
- ``POST orgs/{org_slug}/repos/labels``
- ``repo-label:create``
* - ``labels.get()``
- ``GET orgs/{org_slug}/repos/labels/{label_id}``
- ``repo-label:list``
* - ``labels.delete()``
- ``DELETE orgs/{org_slug}/repos/labels/{label_id}``
- ``repo-label:delete``
* - ``labels.associate()``
- ``POST orgs/{org_slug}/repos/labels/{label_id}/associate``
- ``repo-label:update``
* - ``labels.disassociate()``
- ``POST orgs/{org_slug}/repos/labels/{label_id}/disassociate``
- ``repo-label:update``
* - ``labels.setting.get()``
- ``GET orgs/{org_slug}/repos/labels/{label_id}/label-setting``
- ``repo-label:list``
* - ``labels.setting.put()``
- ``PUT orgs/{org_slug}/repos/labels/{label_id}/label-setting``
- ``repo-label:update``
* - ``labels.setting.delete()``
- ``DELETE orgs/{org_slug}/repos/labels/{label_id}/label-setting``
- ``repo-label:update``
* - ``licensemetadata.post()``
- ``POST license-metadata``
- none
* - ``npm.issues()``
- ``GET npm/{package}/{version}/issues``. Deprecated
- none
* - ``npm.score()``
- ``GET npm/{package}/{version}/score``. Deprecated
- none
* - ``openapi.get()``
- ``GET openapi``
- none
* - ``org.get()``
- ``GET organizations``
- none
* - ``purl.post(org_slug=...)``
- ``POST orgs/{org_slug}/purl``
- ``packages:list``
* - ``purl.post()``
- ``POST purl``. Deprecated
- ``packages:list``
* - ``quota.get()``
- ``GET quota``
- none
* - ``report.list()``
- ``GET report/list``. Deprecated
- ``report:list``
* - ``report.delete()``
- ``DELETE report/delete/{id}``. Deprecated
- ``report:write``
* - ``report.view()``
Comment thread
lelia marked this conversation as resolved.
Resolved
- ``GET report/view/{id}``. Deprecated
- ``report:read``
* - ``report.supported()``
- ``GET report/supported``. Deprecated
- none
* - ``report.create()``
- ``PUT report/upload``. Deprecated
- ``report:write``
* - ``repos.get()``
- ``GET orgs/{org_slug}/repos``
- ``repo:list``
* - ``repos.repo()``
- ``GET orgs/{org_slug}/repos/{repo_slug}``
- ``repo:list``
* - ``repos.post()``
- ``POST orgs/{org_slug}/repos``
- ``repo:create``
* - ``repos.update()``
- ``POST orgs/{org_slug}/repos/{repo_slug}``
- ``repo:update``
* - ``repos.delete()``
- ``DELETE orgs/{org_slug}/repos/{repo_slug}``
- ``repo:delete``
* - ``repositories.list()``
- ``GET repos``
- no such route; the call fails
* - ``sbom.view()``
- ``GET sbom/view/{id}``
- ``report:read`` (not in the API reference)
* - ``settings.get()``
- ``GET orgs/{org_slug}/settings/security-policy``
- ``security-policy:read``
* - ``settings.update_security_policy()``
- ``POST orgs/{org_slug}/settings/security-policy``
- ``security-policy:update``
* - ``settings.get_license_policy()``
- ``GET orgs/{org_slug}/settings/license-policy``. Deprecated
- ``license-policy:read``
* - ``settings.update_license_policy()``
- ``POST orgs/{org_slug}/settings/license-policy``
- ``license-policy:update``
* - ``settings.integration_events()``
Comment thread
lelia marked this conversation as resolved.
Resolved
- ``GET orgs/{org_slug}/settings/integrations/{integration_id}/events``
- ``integration:list``
* - ``supportedfiles.get()``
- ``GET orgs/{org_slug}/supported-files``
- none
* - ``telemetry.get_config()``
- ``GET orgs/{org_slug}/telemetry/config``
- none
* - ``telemetry.update_config()``
- ``PUT orgs/{org_slug}/telemetry/config``
- ``telemetry-policy:update``
* - ``threatfeed.get(org_slug)``
- ``GET orgs/{org_slug}/threat-feed``
- ``threat-feed:list``
* - ``threatfeed.get()``
- ``GET threat-feed``. Deprecated
- ``threat-feed:list``
* - ``triage.list_alert_triage()``
- ``GET orgs/{org_slug}/triage/alerts``
- ``triage:alerts-list``
* - ``triage.update_alert_triage()``
- ``POST orgs/{org_slug}/triage/alerts``
- ``triage:alerts-update``
* - ``uploadmanifests.upload_manifest_files()``
- ``POST orgs/{org_slug}/upload-manifest-files``
- ``full-scans:create`` (not in the API reference)
* - ``webhooks.list()``
- ``GET orgs/{org_slug}/webhooks``
- ``webhooks:list``
* - ``webhooks.create()``
- ``POST orgs/{org_slug}/webhooks``
- ``webhooks:create``
* - ``webhooks.get()``
- ``GET orgs/{org_slug}/webhooks/{webhook_id}``
- ``webhooks:list``
* - ``webhooks.update()``
- ``PUT orgs/{org_slug}/webhooks/{webhook_id}``
- ``webhooks:update``
* - ``webhooks.delete()``
- ``DELETE orgs/{org_slug}/webhooks/{webhook_id}``
- ``webhooks:delete``