> 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).
# 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. Use SOTs for CI/CD pipelines and automated workflows that need authentication independent of any individual user account.
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).
## Token configuration
In addition to setting a token's expiration, SOTs adhere to the principle of least privilege by defining their scope in two dimensions:
* Project access: Restrict the token to specific projects, or grant it access across the entire organization.
* Permissions: Define the specific permissions the token grants. See [Available permissions](#available-permissions) for more details.
**Specific projects** tokens apply the same set of permissions to all selected projects. To modify the project list after creation, see [Modify a token's project scope](#modify-a-tokens-project-scope).
**Organization-wide** tokens have access to all current and future projects in your organization. With the **Create projects and add custom access** permission, the token can also create new projects and automatically receives the project-level permissions you defined on any project it creates.
For supported Web API endpoints, see [SOT Compatible Web API endpoints](#sot-compatible-web-api-endpoints).
### Token status and expiration
The token status reflects its current state:
* Active
* About to expire (in less than 7 days)
* Expired
Tokens configured with **No expiration** show **Never (if used)** in the **Expiry date** column.
When creating a token, choose an expiry date that fits your use case. The expiration date cannot be changed after creation.
If you select **No expiration**, the token is valid for 60 days from the last use, or from the date of creation if it hasn't been used. This option is not recommended — an active token with no expiration remains valid until you revoke it, even if compromised.
### Available permissions
The following project-level permissions are available under **Specific projects**, and under **Create projects and add custom access** for Organization-wide tokens:
| Permission | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Browse** | Allows token access to read project data, measures, quality gate information, and branches/pull requests. It cannot make changes. |
| **Administer projects** | Allows token access to perform supported administrative actions in the selected projects. |
| **Execute analysis** | Allows token access to run analysis for the selected projects. |
The following organization-level permissions are available under **Organization-wide**:
| Permission | Description |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Administer organization** | Allows token access to manage organization settings required for its automation. |
| **Execute analysis for all projects in the organization** | Allows token access to run an analysis for all projects in the organization. |
| **Create projects and add custom access** | Allows token access to create projects and select its Browse, Administer projects, and Execute analysis permissions for each project it creates. |
Each permission grants access only to the Web API endpoints that support it for Scoped Organization Tokens. The available endpoints can differ by permission and evolve over time. See [SOT Compatible Web API endpoints](#sot-compatible-web-api-endpoints).
## Create a token
1. Open 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 **Create token**.
4. In **Details**, enter a name for the token. Select **+ Add description** to add an optional description.
5. In **Expires in**, select the token lifetime. For guidance on choosing a lifetime, see [Token status and expiration](#token-status-and-expiration).
6. Under **Permissions** > **Choose token access**:
* **Specific projects**: Under **Choose the projects**, select **Select projects** and choose which projects the token can access. Select **Edit projects** to change the selection before creating the token. Under **Choose the project permissions**, select one or more permissions to grant on those projects: **Browse**, **Administer projects**, or **Execute analysis**.
* **Organization-wide**: Select one or more of the following permissions:
* **Administer organization**
* **Execute analysis for all projects in the organization**
* **Create projects and add custom access**: Selecting this option expands a set of project-level permissions. Optionally, select one or more permissions the token grants on any project it creates: **Browse**, **Administer projects**, or **Execute analysis**.
7. When finished, select **Generate token**. A message confirms the token was generated and you'll have an option to copy the token to your clipboard.
8. Immediately copy the generated token. Once you close the notification, you cannot view the token value again.
9. Close the notification.
> **Note:** After closing the notification, you can view the token's name, description, expiration date, last used date, and permissions from the token list. See [View a token's details](#view-a-tokens-details) for more information.
## 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. If your integration assigns permissions to SOTs using `POST /users/roles`, see the [Scoped Organization Tokens: API migration guide](/sonarqube-cloud/administering-sonarcloud/managing-organization/scoped-organization-tokens-api-migration.md) to update your API calls.
### 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?deprecated=false&scopedOrganizationTokensCompatible=true`
* US instance: `https://sonarqube.us/web_api?deprecated=false&scopedOrganizationTokensCompatible=true`
> **Note:** SOT Compatible filtering applies to V1 endpoints only. V2 endpoints do not indicate SOT compatibility.
## Manage tokens
### View a token's details
1. Open 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.
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.
### 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 **Organization-wide** access.
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 **Organization-wide** 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, immediately revoke it. Then create a replacement and update your CI/CD configuration with the new value. 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)
* [Scoped Organization Tokens: API migration guide](/sonarqube-cloud/administering-sonarcloud/managing-organization/scoped-organization-tokens-api-migration.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.
