> 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-server/instance-administration/license-management.md).

# License management

Learn how to retrieve, setup, stage and request new SonarQube Server license.

To run SonarQube Server, you need a license that corresponds to the plan you purchased, including the SonarQube Server edition, Lines of Code (LOC), staging licenses, commercial support, and additional features such as Advanced Security. See [Plans and Pricing](https://www.sonarsource.com/plans-and-pricing/sonarqube/) for more information about the different editions and features.

[Contact sales](https://www.sonarsource.com/plans-and-pricing/enterprise/) to request the license key or email us at <contact@sonarsource.com>.

After your purchase is confirmed, you will receive a license key. If the license key follows this format XXXX-XXXX-XXXX-XXXX, continue reading this page. Otherwise, see the [Server ID based license key](/sonarqube-server/instance-administration/license-management/server-id-based-license-key.md) page.

## License types and connectivity <a href="#license-types-and-connectivity" id="license-types-and-connectivity"></a>

SonarQube Server licenses come in two types:

* A LicenseSpring-managed license, identified by a key in the `XXXX-XXXX-XXXX-XXXX` format and manageable through the [#license-user-portal](#license-user-portal "mention"). You activate it either online or offline, see [#online-activation](#online-activation "mention") and [#offline-activation](#offline-activation "mention").
* A [Server ID based license key](/sonarqube-server/instance-administration/license-management/server-id-based-license-key.md), tied to your instance's server ID instead of an activation method, and not managed through the License user portal.

Activation and ongoing connectivity are different requirements, though overage needs both together. Activating a LicenseSpring license, whether online or offline, is a one-time step that does not require your instance to stay connected afterward. Some features need more: overage on the Remediation Agent, Sonar Vortex, Hunter Agent, and Lines of Code (LOC) requires online activation, plus continuous connectivity to LicenseSpring afterward. An instance activated offline is never eligible for overage, even if it later gains network access. See the [Overage activation](/sonarqube-server/instance-administration/license-management/overage-activation.md) page for more details.

To maintain this connectivity, have your network or infrastructure team allow your instance to resolve `api.prod.sonarsource.licensespring.com` and reach it over outbound HTTPS on port 443. If your outbound traffic goes through a proxy, see the [List of properties common to all editions](/sonarqube-server/server-installation/system-properties/common-properties.md#proxy-configuration) page.

The Remediation Agent, Sonar Vortex, and Hunter Agent subscriptions each require a LicenseSpring-managed license, activated either online or offline, rather than a server ID-based license.

## Prerequisites

### Online activation

An internet connection is required to activate your license. SonarQube Server must be able to reach the LicenseSpring server at `https://api.prod.sonarsource.licensespring.com`.

### Offline activation

Use offline activation if either of the following applies:

* SonarQube Server can't reach `https://api.prod.sonarsource.licensespring.com`.
* The filesystem backing the `-Djava.io.tmpdir=/opt/sonarqube/temp` directory (or the path set by `sonar.path.temp` in sonar.properties) is mounted with the `noexec` flag, or an OS security policy (SELinux, seccomp, Kubernetes securityContext, read-only root filesystem, and so on) blocks native code from running there.

## Permissions

To manage your licenses and additional features in SonarQube Server you must have the **Administer System** permission.

To apply the permission to users or groups go to **Administration** > **Security** > **Global permissions** and select the **Administer System** check box.

## Activating your license

To activate your SonarQube Server license:

<figure><img src="https://content.gitbook.com/content/mX1WoFEHhJp6VdSbyTDi/blobs/ue0JePmijeJL9BPvLeok/license-activation-online.png" alt="Set up license modal"><figcaption></figcaption></figure>

1. Go to **Administration** > **Configuration** > **License manager**.
2. Click **Add license** button to open a modal.
3. Enter your license key in the modal and accept the terms and conditions.
4. Click **Set license** to confirm.

An internet connection is required to activate your license. Your instance should be allowed to reach the following resources: `https://api.prod.sonarsource.licensespring.com`

### Activating your license offline

If your SonarQube Server instance is offline and cannot reach the online resource listed in the previous section after you enter the license key, you will have to choose the **Activate offline** option.

<figure><img src="https://4213461411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmX1WoFEHhJp6VdSbyTDi%2Fuploads%2Fgit-blob-ec50eeda3346d85f343a7682985062fbc5251939%2Flicense-offline.png?alt=media" alt="Activate the license offline"><figcaption></figcaption></figure>

Then follow these steps:

1. Click **Download .req file** to download the request file to your computer. You will need this file in the next step.

   <figure><img src="https://4213461411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmX1WoFEHhJp6VdSbyTDi%2Fuploads%2Fgit-blob-af8bfead534e4d202460187a8827cd13da90d3a6%2Flicense-activation-offline.png?alt=media" alt="Downloading .req file during offline license activation"><figcaption></figcaption></figure>
2. Click **Upload .req file** to upload this .req request file to the activation page that opens in a new tab. Alternatively, visit `https://offlinelicense.sonarsource.com` if the server doesn't have access to Internet. Uploading .req file will automatically trigger the download of a .lic license file to your computer.

   <figure><img src="https://4213461411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmX1WoFEHhJp6VdSbyTDi%2Fuploads%2Fgit-blob-7db873bd5a3929737eced7475647e084bc59dbb5%2Flicense-activation-upload.png?alt=media" alt="Uploading .req file during offline license activation"><figcaption></figcaption></figure>
3. Click **Upload .lic file** and locate the .lic file to upload it into your SonarQube Server instance to complete the activation.

   <figure><img src="https://4213461411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmX1WoFEHhJp6VdSbyTDi%2Fuploads%2Fgit-blob-16714b0e1768a3a3cbc7bc772b4ab391bace0904%2Flicense-activation-upload-lic.png?alt=media" alt="Uploading .lic file during offline license activation"><figcaption></figcaption></figure>

## SonarQube Server license page

Once your activation has been completed you will see the following information on the SonarQube license page.

<figure><img src="https://4213461411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmX1WoFEHhJp6VdSbyTDi%2Fuploads%2Fgit-blob-62178c8a3d4100a13d4ff9ba4b9c4c06a46ac3cc%2Fsonarqube-server-license-page.png?alt=media" alt="SonarQube Server license page"><figcaption></figcaption></figure>

1. Select **Set a new license** and enter a new license key to replace your current license. Open the dropdown menu and select **Unset license** to remove it. See [#unsetting-a-license](#unsetting-a-license "mention") for more information.
2. Select **Refresh license** to fetch all the up-to-date information about the license from the license server. This is required if the license was changed by Sonar to update, for example, the maximum LOC. To refresh the offline activated license you can use **Set a new license** with the same license key.
3. **License information**:
   * **Edition**: This is based on the plan you had purchased (Developer, Enterprise or Data Center).
   * **Type**: Type of license, the options are production, test and evaluation.
   * **Start date**: Displays the license start date. **Note**: The start date and time are displayed on the License user portal in the Coordinated Universal Time (UTC).
   * **Expiration date**: Shows when the license expires. **Note**: The expiration date and time are displayed on the License user portal in the Coordinated Universal Time (UTC). The expiration date indicates the first day when the license is no longer active.
   * **Support included**: Indicates whether commercial support is included in your license.
   * **Activation method**: Displays whether the license was activated online, offline or is based on server ID.
   * **License key** currently used.
4. **License usage**:
   * **Lines of code** (LOC): Shows the number of LOC currently analyzed out of the total allowed by your license.
   * **Notification threshold**: Shows the LOC threshold that triggers email notification. Select **Edit threshold** to change it. See [Lines of Code](/sonarqube-server/server-update-and-maintenance/monitoring/lines-of-code.md#checking-your-lines-of-code-consumption) for more information.
5. **Active products**: Lists your Advanced Security, Sonar Vortex, Remediation Agent, and Hunter Agent subscriptions, showing each product's status, base usage limit, and overage limit. See the [Sonar product subscriptions](/sonarqube-server/instance-administration/license-management/product-subscriptions.md) page for more information.

### Activating a product subscription <a href="#activating-a-product-subscription" id="activating-a-product-subscription"></a>

Sonar Vortex, Remediation Agent, and Hunter Agent activate differently from your base SonarQube Server license:

1. Contact your Sonar account representative to subscribe.
2. The Sonar sales team enables the product in LicenseSpring, against your existing license. Your current license key continues to work.
3. For an online-activated license, wait up to 1 hour for the product to appear, or select **Refresh license** to see it immediately. For an offline-activated license, select **Set a new license** and enter the same license key to fetch the update.
4. The product appears in the **Active products** table on this page, with a status of awaiting activation.
5. Select **Enable now** next to the product.
6. Follow the on-screen instructions and agree to the terms of use to complete activation.

Each product has its own setup steps after activation. See the setup overview in [Sonar Vortex](/sonarqube-server/instance-administration/ai-features/sonar-vortex.md#setup-overview), [Remediation Agent](/sonarqube-server/instance-administration/ai-features/remediation-agent.md#setup-overview), or [Hunter Agent](/sonarqube-server/instance-administration/ai-features/hunter-agent.md#setup-overview).

These products each require a LicenseSpring-managed license, rather than a server ID-based one. See [#license-types-and-connectivity](#license-types-and-connectivity "mention") for the difference between the two, and [Sonar product subscriptions](/sonarqube-server/instance-administration/license-management/product-subscriptions.md) for consumption tracking, overage, and notifications.

## Changing server ID

To move your license to an instance with another server ID you have to unset it on the current instance. See [#unsetting-a-license](#unsetting-a-license "mention") for more information.

{% hint style="info" %}
If the license was not unset and it’s no longer possible to do so, for example, due to an incident, contact us at <contact@sonarsource.com> and we will adjust the activation count on the license server for you so you can use the same license on another instance of SonarQube Server. In case you require zero downtime, use the [#break-glass-license](#break-glass-license "mention").
{% endhint %}

### License invalidation scenarios

Certain actions will change your server ID and invalidate your license activation. The following are some of the most common cases:

* Moving, upgrading, or changing your database server to another host, available with a different IP or DNS name.
* Changing the existing database server IP or DNS name.
* Changing the database/schema name on the database server.
* Restoring the database content from another SonarQube Server instance (except for production/staging synchronization).
* Reinstalling SonarQube Server on an empty database.
* Using DBCopy or MySQL Migrator to copy your old database into a new one.

If you plan on going through one of these scenarios and you have commercial support, open a [support ticket](https://help.sonarsource.com/hc/en-us) beforehand to confirm the plan of action or to explore alternatives.

## Unsetting a license

The operation of unsetting a license is necessary in several situations:

* When reusing the license on a different instance with another server ID.
* When changing the server ID of the current instance.
* When applying a different license to the current instance.

### Unsetting a license activated online

To unset a license activated online open the dropdown menu next to **Set a new license** button and select **Unset license** to remove it. Unsetting a license removes it both locally and from the license server and allows you to use it again on another instance or to set a different license on the current instance. Using **Set a new license** button will first unset the current license and then activate a new one.

### Unsetting license activated offline

If you activated your license offline, unsetting the license in SonarQube UI will not remove it from the license server because your SonarQube Server is not connected to it. The license will only be removed locally, and the license server will still consider it activated.

To fully unset the license from the license server, follow these instructions:

1. **Retrieve the .req file**: Use the `POST /api/v2/entitlements/offline-deactivation` endpoint (requires the Administer System permission).
2. **Unset on the license server**: Go to[ https://offlinelicense.sonarsource.com/](https://offlinelicense.sonarsource.com/) and upload the `.req` file retrieved in the previous step.

This process unsets the license on the license server, allowing you to activate it again on an instance with a different server ID.

You can still rely on the **Unset license** or **Set a new license** functionality in SonarQube UI if you need to set another license on the same instance, for example, after a renewal.

## Break glass license

{% hint style="info" %}
Before performing maintenance on your SonarQube Server deployment that could result in a server ID change (see [#changing-server-id](#changing-server-id "mention")), it is highly recommended to first unset the current license. See [#unsetting-a-license](#unsetting-a-license "mention") for more details.
{% endhint %}

You are entitled to a break glass license available in the License user portal along with the production license. The break glass license should be used if the main production license can’t be activated. It expires in 7 days after the day of activation. The process for activating a break-glass license is the same as for a production license.

To reactivate your main production license, reach out to us at <contact@sonarsource.com>.

## Staging license

A staging license is available in Enterprise and Data Center editions, or in editions with commercial support. Your staging license may include one or more activations, which you can use for non-production instances to test new features, for update purposes, new integrations, and other purposes. The process of activating staging licenses is the same as for production.

## License user portal

As soon as a license is created, your organization will receive an email with access to the License user portal, where you can see all available licenses.

### Logging into the License user portal

Sonar License user portal is available at <http://license.sonarsource.com/>.

* Access to the license user portal requires your email address to be registered by Sonar as a license manager for your organization.
* It is recommended to log in using one of the available Single Sign-On (SSO) authentication providers.
* If this is your first time logging in and you are using an email address instead of an SSO provider, you must first **Sign up** to create an account.

<div align="left"><figure><img src="https://content.gitbook.com/content/mX1WoFEHhJp6VdSbyTDi/blobs/XnH5d5pcmNllzcjLrRFW/license-user-portal-login.png" alt="" width="375"><figcaption></figcaption></figure></div>

* Your existing[ Help Center](https://help.sonarsource.com/hc/en-us) account credentials are also valid for accessing the License user portal.

### Checking the license status

<figure><img src="https://content.gitbook.com/content/mX1WoFEHhJp6VdSbyTDi/blobs/Pz7bQXkFl4vQj5CqSRXn/license-user-portal.png" alt="Checking the status of your license"><figcaption></figcaption></figure>

To retrieve the license’s status:

* Select **Licenses** in the left-side navigation to see a list of all licenses for your organization.
* Select a license and navigate to the **Devices** tab.

The **Devices** tab contains a list of SonarQube Server instances. The **Status** column shows the status of the license on that instance, **Active** or **Inactive**. Note that the **Hardware ID** column shows the server ID of your SonarQube Server.

<figure><img src="https://content.gitbook.com/content/mX1WoFEHhJp6VdSbyTDi/blobs/OAB5jYUBfklkBp6ULQSX/license-user-portal-activation-status.png" alt="Viewing the license&#x27;s status"><figcaption></figcaption></figure>

## Need help?

If you're experiencing an issue signing into the portal or activating your license, send an email to <contact@sonarsource.com> and include the following information:

* Server ID found under **Administration** > **System**.
* SonarQube Server version found under **Administration** > **System**.
* Details about the issue you're experiencing, and a screenshot if possible.

## Related pages

* [Server ID based license key](/sonarqube-server/instance-administration/license-management/server-id-based-license-key.md): server ID based activation method
* [Lines of Code](/sonarqube-server/server-update-and-maintenance/monitoring/lines-of-code.md#checking-your-lines-of-code-consumption)
* [Plans and pricing](https://www.sonarsource.com/plans-and-pricing/sonarqube/)
* [Sonar product subscriptions](/sonarqube-server/instance-administration/license-management/product-subscriptions.md)
* [Overage activation](/sonarqube-server/instance-administration/license-management/overage-activation.md)


---

# 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 following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-server/instance-administration/license-management.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

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.