@@ -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