Managing Scoped Organization Tokens
Scoped Organization Tokens (SOTs) provide a secure way to manage non-user-specific authentication.
Overview
Scoped Organization Tokens (SOTs) provide a secure way to manage non-user-specific authentication for your organization. They are attached to an organization, not to an individual user, so they remain valid even when the user who created them leaves your organization.
SOTs are available in the Team and Enterprise plans. You must be an organization admin to create and manage them.
SOTs are identified by the sqco_ prefix. SonarQube's S7791 rule can verify that SOTs are not disclosed within your code.
You can manage SOTs through the UI or through the Authentication domain API.
Scopes and permissions
SOTs adhere to the principle of least privilege by defining their scope in two dimensions:
Project access: Specify which projects within the organization the token can access — a custom selection, or all current and future projects.
Permissions: Define the specific permissions the token grants.
Important: SOTs can currently only be granted the Execute analysis permission. Support for additional permissions is planned.
Token status and expiration
When creating a token, you can set an expiry date or choose no expiration. The token status reflects its current state:
Active
About to expire (in less than 7 days)
Expired
Note: Tokens without an expiry date that have been inactive for 60 days are automatically removed.
Create a token
Retrieve your organization. See Retrieving your organizations for more details.
Go to Scoped Organization Tokens.
In the top right corner, select the Create token button.
Enter the token name and description. Choose a name that accurately represents the token purpose.
In Expires in, select the token lifetime or select No expiration.
In Projects this token can access, select the option you want to use, either a custom selection of projects or all projects within the organization. If you selected Custom selection of projects:
Select the Select projects button. The Projects scope dialog opens.
Select the projects to which the token will give access, as illustrated below.
Close the dialog.
Select the Generate token button. A message pops up to notify the successful token generation.
Immediately copy the generated token from the notification message. Once you've left the notification, you won't be able to view the token value any more.
You can now close the notification.
Use a token with APIs and CI/CD
SOTs authenticate SonarScanner runs by passing the token as the sonar.token property. For CI/CD platform setup options, see the pages about Analyzing source code.
You can also use the Authentication domain API to manage SOTs programmatically.
SOT Compatible Web API endpoints
SOT authentication is supported by a subset of Web API endpoints. In the V1 documentation, SOT Compatible endpoints are labelled SOT Compatible. Enable Show only SOT compatible APIs to filter the endpoint list, or navigate directly to the filtered view for your instance:
EU instance:
https://sonarcloud.io/web_api?scopedOrganizationTokensCompatible=trueUS instance:
https://sonarqube.us/web_api?scopedOrganizationTokensCompatible=true
Note: SOT Compatible filtering currently applies to V1 endpoints. V2 compatibility status is visible in the web API documentation.
Manage tokens
View a token's details
Retrieve your organization. See Retrieving your organizations for more details.
Go to Scoped Organization Tokens. The list of tokens is displayed.
In the list of tokens, locate the token you want to view and select the Actions menu at the end of the row.
In the menu, select View details. The token details are displayed as illustrated below.
Revoke a token
When you revoke a Scoped Organization Token, it's automatically deleted.
View the token as described in View a token's details.
In the Actions menu, select Revoke. A confirmation dialog opens.
Confirm. The token disappears from the list of tokens.
Modify a token's project scope
You can modify the custom list of projects to which a Scoped Organization Token gives access.
Important: You cannot modify the scope of a Scoped Organization Token configured for all current and future projects.
View the token as described in View a token's details.
In the Actions menu, select View details.
Select the Edit projects button. The Projects scope dialog opens.
Change the project selection.
Select Close.
Security guidance
The following recommendations reflect common best practices. Review them in the context of your organization's existing security policies and CI/CD environment.
Set an expiration date
Always set an expiration date. For CI/CD pipelines that run frequently, 30 to 90 days balances security with maintenance overhead. Avoid No expiration. Tokens without an expiry date are removed automatically after 60 days of inactivity, but an active token that is compromised remains valid until you revoke it.
Limit project scope
Grant access only to the specific projects a pipeline analyzes. Reserve the All current and future projects option for org-wide pipelines. Using it for a single-project pipeline unnecessarily broadens the token's reach.
Store tokens in secret storage
Never store token values in source code or plain-text configuration files. Store them in your CI/CD platform's secret management (such as GitHub Actions secrets or Azure Pipelines secret variables), or in a secrets manager such as HashiCorp Vault or AWS Secrets Manager. Pass the value to the scanner as the sonar.token property at runtime.
Rotate tokens after exposure
If a token is compromised or suspected exposed, create a replacement first, update your CI/CD configuration with the new value, then revoke the original. The sqco_ prefix lets SonarQube's S7791 rule detect SOTs disclosed in your code.
Audit and clean up regularly
Periodically review the Scoped Organization Tokens list and revoke tokens that are expired, inactive, or no longer needed.
Related pages
Related online courses
Last updated
Was this helpful?