Socket API Tokens

API tokens are required to use the Socket CLI or Socket REST API. They can be managed in the dashboard. Audits of last usage and remaining quota are available on the dashboard. Quotas can also be queried using the Socket REST API. Ensure your API tokens are stored securely and rotate them if you have concerns about their usage.

Scopes

API Tokens can individually manage the capabilities they can use in our API. These capabilities can be managed in the dashboard using the menu for editing API tokens.

API Token Scopes

Scope	Description
`alerts:list`	List all alerts.
`alerts:trend`	View alert trend reports over time.
`api-tokens:create`	Create API tokens.
`api-tokens:update`	Update API tokens.
`api-tokens:revoke`	Revoke API tokens.
`api-tokens:rotate`	Rotate API tokens.
`api-tokens:list`	List all API tokens.
`audit-log:list`	List audit log events.
`dependencies:list`	List dependencies.
`dependencies:trend`	View dependency trend reports.
`full-scans:list`	List full scans.
`full-scans:create`	Create full scans.
`full-scans:delete`	Delete full scans.
`historical:snapshots-list`	List metadata for periodic historical snapshots.
`historical:snapshots-start`	Start a new historical snapshot job.
`historical:alerts-list`	List historical alerts.
`historical:alerts-trend`	View historical alert trend reports.
`historical:dependencies-list`	List historical dependencies.
`historical:dependencies-trend`	View historical dependency trend reports.
`integration:list`	List integrations.
`integration:create`	Create integrations.
`integration:update`	Update integrations.
`integration:delete`	Delete integrations.
`license-policy:update`	Update license policies.
`license-policy:read`	Read license policies.
`packages:list`	List package metadata.
`report:list`	List reports.
`report:read`	Read report data.
`report:write`	Create reports.
`repo:list`	List repositories.
`repo:create`	Create repositories.
`repo:update`	Update repositories.
`repo:delete`	Delete repositories.
`security-policy:update`	Update security policies.
`security-policy:read`	Read security policies.
`threat-feed:list`	List threat feed items.
`triage:alerts-list`	List alert triage states.
`triage:alerts-update`	Update alert triage states.

Example Usage

A security team may wish to create a list of restricted tokens available by default general consumption on machines with limited privileges.

The security team creates an API token in the Socket dashboard.
The security team edits the scopes of the API token in the Socket dashboard to only have report:read and report:write.
The security team gives the API token to developers wishing to run reports locally.
The developers can create reports without being able to see reports generated by other developers.

Visibility

API Tokens can be shown to different groups of people depending upon their visibility settings. This visibility can be changed in the dashboard using the menu for editing API tokens.

Visibility	Description
Admin only (default)	Only administrators of the Socket organization can view the API token and copy its value.
Organization members	All users that have joined the Socket organization can view the API token and copy its value.

The visibility of a token does not grant the capability to edit a token. Only organization administrators can create or edit API tokens.

Example Usage

A security team may wish to allow developers to get a list of self service API tokens from Socket's dashboard without intervention by the security team.

The security team creates an API token in the Socket dashboard.
The security team ensure the API token has the correct scopes.
The security team changes the API token visibility to be viewable by all members of the Socket organization.
The security team invites people as members to the Socket organization either by email, or by GitHub integration automatically.
These people can join the organization as members by accepting the invitation.
These members see the API tokens by visiting the Socket dashboard.

Rotation

API Tokens can be shown to disabled and forcibly rotated in the case of incidents requiring action. In case of such an incident if a team needs to rotate API tokens, they can go to the dashboard and individually rotate keys one at a time using the menu for editing API tokens.

Rotating an API token will preserve its name, visibility, and scopes. Please note that if an API token is visible to a user in the dashboard it will remain visible even after rotation. To prevent tokens from being visible during or after rotation please edit the visibility first before rotating the API token.

Other search terms for this page: API Keys, Access Tokens, App Token, API Credential