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.
| Scope | Description |
|---|---|
| report | Grants all permissions provided by report:* scopes |
| report:list | Allows an API token to be used to get a list of all reports it has access to |
| report:read | Allows an API token to be used to read the results of reports it has access to |
| report:write | Allows an API token to be used to create reports |
| repo | Grants all permissions provided by repo:* scopes |
| repo:list | Allows an API token to be used to get a list of all git repositories it has associated with it |
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
Updated 4 months ago