> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-cloud/administering-sonarcloud/managing-organization/scoped-organization-tokens.md). # Managing Scoped Organization Tokens ## 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](https://api-docs.sonarsource.com/sonarqube-cloud/default/public-externalauthentication-0-0). ## 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 1. Retrieve your organization. See [Retrieving your organizations](/sonarqube-cloud/getting-started/viewing-organizations.md) for more details. 2. Go to **Scoped Organization Tokens**. 3. In the top right corner, select the **Create token** button.
Creating a token form
4. Enter the token name and description. Choose a name that accurately represents the token purpose. 5. In **Expires in**, select the token lifetime or select **No expiration**. 6. 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**: 1. Select the **Select projects** button. The **Projects scope** dialog opens. 2. Select the projects to which the token will give access, as illustrated below. 3. Close the dialog. 7. Select the **Generate token** button. A message pops up to notify the successful token generation. 8. 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.
Select the copy tool located at the right of the generated token to copy and then paste the token.
9. 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](/sonarqube-cloud/analyzing-source-code.md). You can also use the [Authentication domain API](https://api-docs.sonarsource.com/sonarqube-cloud/default/public-externalauthentication-0-0) 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=true` * US 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 1. Retrieve your organization. See [Retrieving your organizations](/sonarqube-cloud/getting-started/viewing-organizations.md) for more details. 2. Go to **Scoped Organization Tokens**. The list of tokens is displayed.
Retrieving scoped organization tokens
3. In the list of tokens, locate the token you want to view and select the **Actions** menu at the end of the row. 4. In the menu, select **View details**. The token details are displayed as illustrated below.
Scope organization tokens details
### Revoke a token When you revoke a Scoped Organization Token, it's automatically deleted. 1. View the token as described in [#view-a-tokens-details](#view-a-tokens-details "mention"). 2. In the **Actions** menu, select **Revoke**. A confirmation dialog opens. 3. 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. 1. View the token as described in [#view-a-tokens-details](#view-a-tokens-details "mention"). 2. In the **Actions** menu, select **View details**. 3. Select the **Edit projects** button. The **Projects scope** dialog opens. 4. Change the project selection. 5. 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 * [Web API](/sonarqube-cloud/appendices/web-api.md) ## Related online courses * :video: [Creating scoped organization tokens in SonarQube Cloud](https://www.sonarsource.com/learn/course/sonarqube-cloud/86ad9781-cfb5-4c02-b141-1fe776843827/creating-scoped-organization-tokens-in-sonarqube-cloud) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sonarsource.com/sonarqube-cloud/administering-sonarcloud/managing-organization/scoped-organization-tokens.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.