Skip to content

Commit 28e78d7

Browse files
committed
Document the API token scopes each SDK method needs
Add an "API token scopes" section to the README that maps every SDK method to the endpoint it calls and the scopes that endpoint checks, matching the per-endpoint scopes in the public API reference. It also explains how a 401 or 403 surfaces: a missing scope raises APIAccessDenied with status_code 403 and the server's "Insufficient permissions" message, and 403s with more specific messages raise APIInsufficientPermissions, APIOrganizationNotAllowed or APIInsufficientQuota, all subclasses of APIFailure. Methods whose endpoint the reference does not list are marked as such rather than given a guessed scope.
1 parent 809722c commit 28e78d7

1 file changed

Lines changed: 349 additions & 1 deletion

File tree

‎README.rst‎

Lines changed: 349 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Initializing the module
2424
2525
**PARAMETERS:**
2626

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

14991499
- **org_slug (str)** - The organization slug
15001500
- **query_params (dict, optional)** - Optional query parameters for filtering
1501+
1502+
1503+
API token scopes
1504+
----------------
1505+
1506+
The SDK authenticates every call with one organization API token, and each Socket API
1507+
endpoint checks that the token carries particular scopes. The table below lists, for each
1508+
SDK method, the endpoint it calls and the scopes that endpoint checks. Where an endpoint
1509+
lists more than one scope, the token needs all of them. "none" means any valid token for
1510+
the organization works. Paths are relative to ``https://api.socket.dev/v0/``; query strings
1511+
are omitted.
1512+
1513+
The scopes each endpoint checks are also listed in the
1514+
`API reference <https://docs.socket.dev/reference>`_. For a least-privilege token, grant
1515+
only the scopes of the methods your integration calls.
1516+
1517+
Missing scopes and other 403 responses
1518+
""""""""""""""""""""""""""""""""""""""
1519+
1520+
Methods do not return an empty result on a 401 or 403. ``API.do_request()`` raises
1521+
before the method sees the response, so the exception reaches the caller, including when
1522+
``use_types=True``.
1523+
1524+
A missing scope raises ``APIAccessDenied`` with ``status_code`` 403. Its message starts
1525+
with the server's ``Insufficient permissions``, followed by the request URL and the
1526+
response headers. A 401, from a bad or revoked token, also raises ``APIAccessDenied``,
1527+
with ``Unauthorized`` in the message.
1528+
1529+
Recent API responses name the required scopes in the 403 body under
1530+
``error.details.requiredScopes``, but the SDK does not include them in the exception
1531+
message; to see them, look up the endpoint in the table below or the API reference.
1532+
1533+
A 403 whose ``error.message`` contains one of these texts raises a more specific class
1534+
instead, and logs the server's message at ``ERROR`` on the ``socketdev`` logger:
1535+
1536+
- ``Insufficient permissions for API method``: ``APIInsufficientPermissions``
1537+
- ``Organization not allowed``: ``APIOrganizationNotAllowed``
1538+
- ``Insufficient max quota``: ``APIInsufficientQuota`` (a 429 also raises this class)
1539+
1540+
All of these classes live in ``socketdev.exceptions``, carry the HTTP status in
1541+
``status_code`` and subclass ``APIFailure``, so catching ``APIFailure`` covers every
1542+
case.
1543+
1544+
.. code-block:: python
1545+
1546+
from socketdev import socketdev
1547+
from socketdev.exceptions import APIAccessDenied
1548+
1549+
socket = socketdev(token="REPLACE_ME")
1550+
try:
1551+
socket.diffscans.list("org_slug")
1552+
except APIAccessDenied as error:
1553+
if error.status_code == 403:
1554+
print("Access denied; check the token's scopes for this method:", error)
1555+
raise
1556+
1557+
Scopes by method
1558+
""""""""""""""""
1559+
1560+
A few rows need a note:
1561+
1562+
- ``fullscans.finalize_tier1()`` and ``uploadmanifests.upload_manifest_files()`` call
1563+
endpoints the API reference does not list. Both check ``full-scans:create``.
1564+
- Rows marked "not in the API reference" call an endpoint the current reference does not
1565+
list, so no scope is documented for it. ``repositories.list()`` and ``sbom.view()``
1566+
belong to the deprecated report-era API. ``settings.integration_events()`` calls
1567+
``settings/integrations/{integration_id}``; the reference lists the integration events
1568+
endpoint as ``settings/integrations/{integration_id}/events``, which checks
1569+
``integration:list``.
1570+
- Some scopes differ from what the method name suggests: ``analytics.get_org()`` and
1571+
``analytics.get_repo()`` check ``report:write``; ``apitokens.update()`` checks
1572+
``api-tokens:create``; ``labels.setting.delete()`` checks ``repo-label:update``; and
1573+
the ``export`` methods check ``report:read`` rather than a full-scans scope.
1574+
1575+
.. list-table::
1576+
:header-rows: 1
1577+
:widths: 30 45 25
1578+
1579+
* - Method
1580+
- Endpoint
1581+
- Scopes
1582+
* - ``alertfullscansearch.search()``
1583+
- ``GET orgs/{org_slug}/alert-full-scan-search``
1584+
- ``alerts:list``
1585+
* - ``alerts.get()``
1586+
- ``GET orgs/{org_slug}/alerts``
1587+
- ``alerts:list``
1588+
* - ``alerttypes.get()``
1589+
- ``POST alert-types``
1590+
- none
1591+
* - ``analytics.get_org()``
1592+
- ``GET analytics/org/{filter}``
1593+
- ``report:write``
1594+
* - ``analytics.get_repo()``
1595+
- ``GET analytics/repo/{name}/{filter}``
1596+
- ``report:write``
1597+
* - ``apitokens.create()``
1598+
- ``POST orgs/{org_slug}/api-tokens``
1599+
- ``api-tokens:create``
1600+
* - ``apitokens.list()``
1601+
- ``GET orgs/{org_slug}/api-tokens``
1602+
- ``api-tokens:list``
1603+
* - ``apitokens.update()``
1604+
- ``POST orgs/{org_slug}/api-tokens/update``
1605+
- ``api-tokens:create``
1606+
* - ``apitokens.update(token_id=...)``
1607+
- ``PUT orgs/{org_slug}/api-tokens/{token_id}``
1608+
- not in the API reference
1609+
* - ``apitokens.rotate()``
1610+
- ``POST orgs/{org_slug}/api-tokens/rotate``
1611+
- ``api-tokens:rotate``
1612+
* - ``apitokens.revoke()``
1613+
- ``POST orgs/{org_slug}/api-tokens/revoke``
1614+
- ``api-tokens:revoke``
1615+
* - ``auditlog.get()``
1616+
- ``GET orgs/{org_slug}/audit-log``
1617+
- ``audit-log:list``
1618+
* - ``basics.get_config()``
1619+
- ``GET orgs/{org_slug}/settings/socket-basics``
1620+
- ``socket-basics:read``
1621+
* - ``dependencies.post()``
1622+
- ``POST dependencies/upload``
1623+
- ``report:write``
1624+
* - ``dependencies.get()``
1625+
- ``POST dependencies/search``
1626+
- none
1627+
* - ``dependencies.get(org_slug, ecosystem, package, version)``
1628+
- ``GET orgs/{org_slug}/dependencies/{ecosystem}/{package}/{version}``
1629+
- not in the API reference
1630+
* - ``diffscans.list()``
1631+
- ``GET orgs/{org_slug}/diff-scans``
1632+
- ``diff-scans:list``
1633+
* - ``diffscans.get()``
1634+
- ``GET orgs/{org_slug}/diff-scans/{diff_scan_id}``
1635+
- ``diff-scans:list``
1636+
* - ``diffscans.create_from_repo()``
1637+
- ``POST orgs/{org_slug}/diff-scans/from-repo/{repo_slug}``
1638+
- ``diff-scans:create``, ``full-scans:create`` and ``repo:list``
1639+
* - ``diffscans.create_from_ids()``
1640+
- ``POST orgs/{org_slug}/diff-scans/from-ids``
1641+
- ``diff-scans:create`` and ``full-scans:list``
1642+
* - ``diffscans.gfm()``
1643+
- ``GET orgs/{org_slug}/diff-scans/{diff_scan_id}/gfm``
1644+
- ``diff-scans:list``
1645+
* - ``diffscans.delete()``
1646+
- ``DELETE orgs/{org_slug}/diff-scans/{diff_scan_id}``
1647+
- ``diff-scans:delete``
1648+
* - ``export.cdx_bom()``
1649+
- ``GET orgs/{org_slug}/export/cdx/{id}``
1650+
- ``report:read``
1651+
* - ``export.spdx_bom()``
1652+
- ``GET orgs/{org_slug}/export/spdx/{id}``
1653+
- ``report:read``
1654+
* - ``export.openvex_bom()``
1655+
- ``GET orgs/{org_slug}/export/openvex/{id}``
1656+
- ``report:read``
1657+
* - ``fixes.get()``
1658+
- ``GET orgs/{org_slug}/fixes``
1659+
- ``fixes:list``
1660+
* - ``fullscans.get()``
1661+
- ``GET orgs/{org_slug}/full-scans``, or ``GET orgs/{org_slug}/full-scans/{full_scan_id}`` when ``params`` holds only ``id``
1662+
- ``full-scans:list``
1663+
* - ``fullscans.post()``
1664+
- ``POST orgs/{org_slug}/full-scans``
1665+
- ``full-scans:create``
1666+
* - ``fullscans.delete()``
1667+
- ``DELETE orgs/{org_slug}/full-scans/{full_scan_id}``
1668+
- ``full-scans:delete``
1669+
* - ``fullscans.stream_diff()``
1670+
- ``GET orgs/{org_slug}/full-scans/diff``
1671+
- ``full-scans:list``
1672+
* - ``fullscans.stream()``
1673+
- ``GET orgs/{org_slug}/full-scans/{full_scan_id}``
1674+
- ``full-scans:list``
1675+
* - ``fullscans.metadata()``
1676+
- ``GET orgs/{org_slug}/full-scans/{full_scan_id}/metadata``
1677+
- ``full-scans:list``
1678+
* - ``fullscans.gfm()``
1679+
- ``GET orgs/{org_slug}/full-scans/diff/gfm``
1680+
- ``full-scans:list``
1681+
* - ``fullscans.finalize_tier1()``
1682+
- ``POST tier1-reachability-scan/finalize``
1683+
- ``full-scans:create`` (not in the API reference)
1684+
* - ``fullscans.archive()``
1685+
- ``POST orgs/{org_slug}/full-scans/archive``
1686+
- ``full-scans:create``
1687+
* - ``fullscans.rescan()``
1688+
- ``POST orgs/{org_slug}/full-scans/{full_scan_id}/rescan``
1689+
- ``full-scans:create``
1690+
* - ``fullscans.get_tar_files()``
1691+
- ``GET orgs/{org_slug}/full-scans/{full_scan_id}/files/tar``
1692+
- ``full-scans:list``
1693+
* - ``historical.list()``
1694+
- ``GET orgs/{org_slug}/historical/alerts``
1695+
- ``historical:alerts-list``
1696+
* - ``historical.trend()``
1697+
- ``GET orgs/{org_slug}/historical/alerts/trend``
1698+
- ``historical:alerts-trend``
1699+
* - ``historical.dependencies_trend()``
1700+
- ``GET orgs/{org_slug}/historical/dependencies/trend``
1701+
- ``historical:dependencies-trend``
1702+
* - ``historical.snapshots.create()``
1703+
- ``POST orgs/{org_slug}/historical/snapshots``
1704+
- ``historical:snapshots-start``
1705+
* - ``historical.snapshots.list()``
1706+
- ``GET orgs/{org_slug}/historical/snapshots``
1707+
- ``historical:snapshots-list``
1708+
* - ``labels.list()``
1709+
- ``GET orgs/{org_slug}/repos/labels``
1710+
- ``repo-label:list``
1711+
* - ``labels.post()``
1712+
- ``POST orgs/{org_slug}/repos/labels``
1713+
- ``repo-label:create``
1714+
* - ``labels.get()``
1715+
- ``GET orgs/{org_slug}/repos/labels/{label_id}``
1716+
- ``repo-label:list``
1717+
* - ``labels.delete()``
1718+
- ``DELETE orgs/{org_slug}/repos/labels/{label_id}``
1719+
- ``repo-label:delete``
1720+
* - ``labels.associate()``
1721+
- ``POST orgs/{org_slug}/repos/labels/{label_id}/associate``
1722+
- ``repo-label:update``
1723+
* - ``labels.disassociate()``
1724+
- ``POST orgs/{org_slug}/repos/labels/{label_id}/disassociate``
1725+
- ``repo-label:update``
1726+
* - ``labels.setting.get()``
1727+
- ``GET orgs/{org_slug}/repos/labels/{label_id}/label-setting``
1728+
- ``repo-label:list``
1729+
* - ``labels.setting.put()``
1730+
- ``PUT orgs/{org_slug}/repos/labels/{label_id}/label-setting``
1731+
- ``repo-label:update``
1732+
* - ``labels.setting.delete()``
1733+
- ``DELETE orgs/{org_slug}/repos/labels/{label_id}/label-setting``
1734+
- ``repo-label:update``
1735+
* - ``licensemetadata.post()``
1736+
- ``POST license-metadata``
1737+
- none
1738+
* - ``npm.issues()``
1739+
- ``GET npm/{package}/{version}/issues``
1740+
- none
1741+
* - ``npm.score()``
1742+
- ``GET npm/{package}/{version}/score``
1743+
- none
1744+
* - ``openapi.get()``
1745+
- ``GET openapi``
1746+
- none
1747+
* - ``org.get()``
1748+
- ``GET organizations``
1749+
- none
1750+
* - ``purl.post(org_slug=...)``
1751+
- ``POST orgs/{org_slug}/purl``
1752+
- ``packages:list``
1753+
* - ``purl.post()``
1754+
- ``POST purl``
1755+
- ``packages:list``
1756+
* - ``quota.get()``
1757+
- ``GET quota``
1758+
- none
1759+
* - ``report.list()``
1760+
- ``GET report/list``
1761+
- ``report:list``
1762+
* - ``report.delete()``
1763+
- ``DELETE report/delete/{id}``
1764+
- ``report:write``
1765+
* - ``report.view()``
1766+
- ``GET report/view/{id}``
1767+
- ``report:read``
1768+
* - ``report.supported()``
1769+
- ``GET report/supported``
1770+
- none
1771+
* - ``report.create()``
1772+
- ``PUT report/upload``
1773+
- ``report:write``
1774+
* - ``repos.get()``
1775+
- ``GET orgs/{org_slug}/repos``
1776+
- ``repo:list``
1777+
* - ``repos.repo()``
1778+
- ``GET orgs/{org_slug}/repos/{repo_slug}``
1779+
- ``repo:list``
1780+
* - ``repos.post()``
1781+
- ``POST orgs/{org_slug}/repos``
1782+
- ``repo:create``
1783+
* - ``repos.update()``
1784+
- ``POST orgs/{org_slug}/repos/{repo_slug}``
1785+
- ``repo:update``
1786+
* - ``repos.delete()``
1787+
- ``DELETE orgs/{org_slug}/repos/{repo_slug}``
1788+
- ``repo:delete``
1789+
* - ``repositories.list()``
1790+
- ``GET repos``
1791+
- not in the API reference
1792+
* - ``sbom.view()``
1793+
- ``GET sbom/view/{id}``
1794+
- not in the API reference
1795+
* - ``settings.get()``
1796+
- ``GET orgs/{org_slug}/settings/security-policy``
1797+
- ``security-policy:read``
1798+
* - ``settings.update_security_policy()``
1799+
- ``POST orgs/{org_slug}/settings/security-policy``
1800+
- ``security-policy:update``
1801+
* - ``settings.get_license_policy()``
1802+
- ``GET orgs/{org_slug}/settings/license-policy``
1803+
- ``license-policy:read``
1804+
* - ``settings.update_license_policy()``
1805+
- ``POST orgs/{org_slug}/settings/license-policy``
1806+
- ``license-policy:update``
1807+
* - ``settings.integration_events()``
1808+
- ``GET orgs/{org_slug}/settings/integrations/{integration_id}``
1809+
- not in the API reference
1810+
* - ``supportedfiles.get()``
1811+
- ``GET orgs/{org_slug}/supported-files``
1812+
- none
1813+
* - ``telemetry.get_config()``
1814+
- ``GET orgs/{org_slug}/telemetry/config``
1815+
- none
1816+
* - ``telemetry.update_config()``
1817+
- ``PUT orgs/{org_slug}/telemetry/config``
1818+
- ``telemetry-policy:update``
1819+
* - ``threatfeed.get(org_slug)``
1820+
- ``GET orgs/{org_slug}/threat-feed``
1821+
- ``threat-feed:list``
1822+
* - ``threatfeed.get()``
1823+
- ``GET threat-feed``
1824+
- ``threat-feed:list``
1825+
* - ``triage.list_alert_triage()``
1826+
- ``GET orgs/{org_slug}/triage/alerts``
1827+
- ``triage:alerts-list``
1828+
* - ``triage.update_alert_triage()``
1829+
- ``POST orgs/{org_slug}/triage/alerts``
1830+
- ``triage:alerts-update``
1831+
* - ``uploadmanifests.upload_manifest_files()``
1832+
- ``POST orgs/{org_slug}/upload-manifest-files``
1833+
- ``full-scans:create`` (not in the API reference)
1834+
* - ``webhooks.list()``
1835+
- ``GET orgs/{org_slug}/webhooks``
1836+
- ``webhooks:list``
1837+
* - ``webhooks.create()``
1838+
- ``POST orgs/{org_slug}/webhooks``
1839+
- ``webhooks:create``
1840+
* - ``webhooks.get()``
1841+
- ``GET orgs/{org_slug}/webhooks/{webhook_id}``
1842+
- ``webhooks:list``
1843+
* - ``webhooks.update()``
1844+
- ``PUT orgs/{org_slug}/webhooks/{webhook_id}``
1845+
- ``webhooks:update``
1846+
* - ``webhooks.delete()``
1847+
- ``DELETE orgs/{org_slug}/webhooks/{webhook_id}``
1848+
- ``webhooks:delete``

0 commit comments

Comments
 (0)