# License Management

Users with an installation of Form.io within their own Self-Hosted private cloud or on-premise environment will manage the utilization[^1] of the Projects within that environment through valid License Key(s). These keys are implemented within the [**environment variables**](../../deployment-guide/enterprise-server#license-environment-variable-required) for the associated deployment and managed by [Licensed Manager](#user-content-fn-2)[^2] users.&#x20;

## Accessing License Management

To access and manage the keys, License Managers will log into the SaaS portal at [**portal.form.io**](https://portal.form.io/#/) and navigate to the License Management page found in the left-hand navigation bar, or by clicking the username dropdown. You must be a License Manager User to access and manage the License Key.&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FTi7EeXfdn2vc5FssgQUj%2Flicensemanageportal.jpg?alt=media&#x26;token=14243873-ede3-4e05-8be8-928eaadc9555" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Contact **support@form.io** to become a License Manager for your deployment&#x20;
{% endhint %}

## License Manager UI

The License Management page will display all licenses associated with the License Manager's account. The License line item will summarize information such as the License Key name, Start/End dates, and all the Managers associated with the License Key. Users will typically only have one license key they manage, but some users may have multiple keys associated with different environments.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FnRDx8hVfQk6dWhgVONnf%2Flicense.jpg?alt=media&#x26;token=9a8fd2ee-429a-4c83-8137-13a4d6f6d294" alt=""><figcaption></figcaption></figure>

Clicking the carrot icon next to the License Key Name will expand the License details. The left-hand navigation tabs will guide the user through all of the utilization options such as API and PDF Servers, Projects,  and Tenants.&#x20;

{% hint style="info" %}
Not all of these utilizations will be available depending on what has been purchased for your specific License.&#x20;
{% endhint %}

## **API / PDF Server**

Clicking the [**API**](../deployment-guide/enterprise-server) or [**PDF**](../deployment-guide/pdf-server) Server tab will display all of the servers associated with the License.  information for the servers such as what environment the server resides in, and the ability to manage the utilization. \
\
For example, you may need to disable the status of one API server to provide an allocation to a different server you're trying to spin up.&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FXsNUv2bGccU1VClOH8Gy%2Flicenseservers.jpg?alt=media&#x26;token=09d47114-5a24-4851-93d3-4fddf0b93ae0" alt=""><figcaption></figcaption></figure>

**Environment ID**: The Environment ID the Server is associated with. Use the status endpoint within your environment to view the ID associated with your deployment:

`https://myenvironment.com/status`&#x20;

The URL will output the server version, the associated schema, and the Environment ID. The Environment ID can then be matched up with the ID found within the License Management page. This can help you determine what environment the server resides in.

<pre><code><strong>{"version":"9.3.0","schema":"3.3.17","environmentId":"64760b724279d9df47xxxxxx"}
</strong></code></pre>

{% hint style="info" %}
The PDF server will have the same environment ID as the API Server if the two servers are associated with the same database string within the environment.&#x20;
{% endhint %}

**Host Name**: Links an environment with the Enterprise server network host it was created on.&#x20;

**Mongo Hash**: MD5 hash of the mongoDB configuration which is useful for server logging and is an additional way to tie the _user's_ database to the associated environment

**Status Toggle:** Click the Toggle to disable the server utilization for the environment. Disabling will free up another server utilization for your environment. Disabling or deleting the utilization will not spin down the server. See [**Deleting a License Utilization**](#deleting-a-license-utilization) for more information

**Delete:** Removes the server utilization from the License Management UI. This does **not** disable the functionality of the server within the self-hosted environment.

## Projects

The [**Project**](../../userguide/projects) tab lists all Projects associated with the given License Key. License Managers can manage the utilization of the Project, Stages, and connected Form Manager Applications.&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FTeK8ueouVCYWFRanYCJe%2Flicenseprojects.jpg?alt=media&#x26;token=45eff90b-17f9-430d-b08c-68aaffd69dae" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To reinstall the Portal Base Project, **delete** the project within the Database, **restart** the environment container,  and the Portal Base Project will be **recreated**.&#x20;

Simply deleting the Portal Base Project and reinstalling it will inadvertently consume a Project allocation within the license scope.&#x20;
{% endhint %}

**Title:** Title of the Project

**Name:** The live endpoint name of the Project

**FM:** When checked, indicates if the Form Manager application is enabled for the Project. Clicking the carrot icon next to the Project title will show which stage within that project has the Form Manager enabled.&#x20;

**Project ID:** ID found within the environment URL of the Project

**Environment ID:** The Environment ID the project resides in. This ID will match the associated server Environment ID within the same license.&#x20;

**Status / Delete:**  Click the Status to disable the project utilization and delete to remove the utilization from the License Management UI.  Disabling or deleting the utilization will not remove the project from the environment. See [**Deleting a License Utilization**](#deleting-a-license-utilization) for more information

**Stages:** [**Stage**](../../userguide/projects/stages) utilization associated with the Project. License Managers can modify the utilization of these Stages just like the Project utilization. Each Project will have 7 utilization stages available.

## Tenants

The [**Tenants**](../../userguide/projects/tenants) tab lists all associated Tenants within the given License Key and Project.  License Managers can manage the utilization of all Tenants within the License Key. Expanding the Tenant line item will display all Stages within that Tenant. The same Project and Stage utilization information is available here including IDs and the ability to disable the utilization.&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FSeYK8o0IPJYS3RJggwBx%2Flicensetenants.jpg?alt=media&#x26;token=a268cbe3-73d6-4617-a8c9-bdf0863d34e2" alt=""><figcaption></figcaption></figure>

## Deleting a License Utilization

Deleting a License utilization like an API Server, Project, or Tenant from the License Management page does **not** delete this item from the database. When deleted, the utilization is simply removed from the License Key which is helpful when cleaning up the UI for unused utilizations.&#x20;

Deleted Project, Stage, or Tenant utilizations will reactivate if the Project or Stage is opened again by a user within the self-hosted environment.

Spinning down an API or PDF server from the database does not remove the associated License utilization and will need to be manually removed or disabled within the License Management UI.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FWlyXglKEPac9UC0hPQTk%2Flicensestatusdelete.jpg?alt=media&#x26;token=76b19fd4-7185-4645-8eca-c1e080299504" alt=""><figcaption></figcaption></figure>

## License Management Troubleshooting

If your Form.io deployment is experiencing license errors, it could be due to several reasons. It's important to note that when a Form.io License fails, the platform and form functionality are affected differently depending on the type of license failure that has occurred. Here are the most common causes, the type of failure that can happen, and how to fix them:

{% hint style="info" %}
* If your License issue persists after reading through this troubleshooting guide, contact support@form.io.
* Before diagnosing a Form.io License failure in a deployed or cloud environment, it's important to **review your server logs**. These logs offer valuable insights into errors or connection failures, helping you resolve the problem more efficiently.
{% endhint %}

### License Server Connectivity Issues

Form.io’s license verification process requires your **server** or **application** to communicate with Form.io’s **license server**. If there are network restrictions in place, such as firewalls, VPNs, or proxy settings, these can block the connection, leading to license validation failures. Most license connection issues occur when the server deployment is incorrectly configured, preventing a successful connection to the license server.

**What can cause a License Server connection issue?**

* **Firewalls Blocking Outbound Requests**\
  Ensure that your server can send outbound requests to the License server
* **Proxy Servers or VPNs Interfering with Requests**\
  If your environment requires outgoing traffic to go through a proxy server, ensure your Form.io requests are correctly routed:
* **Cloud Provider Security Rules (AWS, Azure, GCP, etc.)**\
  Update the Cloud Provider security rules to allow outbound HTTPS traffic to the license server.&#x20;

#### What happens if the Form.io license server connection is lost:

* A **12-hour grace period** starts if the environment can't communicate with the license server.
* During this grace period, the platform and forms will function as normal.
* After the 12 hour grace period expires, the server enters **restricted mode**. During this time, any **PUT, PATCH, and DELETE** requests return **503 errors** (excluding form draft PUTs).
* **Reconnecting** to the license server restores full functionality.

### Invalid License

When the server detects an invalid license, it will immediately shut down, requiring a valid license key or an update to the license expiration date.

{% hint style="info" %}
Contact support@form.io to verify or renew your license&#x20;
{% endhint %}

**What can cause an Invalid License?**&#x20;

* **Missing License Variable**\
  The LICENSE\_KEY  variable is missing from the environment variables.&#x20;
* **Invalid License Key**\
  The License Key saved within the environmental variables of the deployment is invalid. Update the variable with a valid key and restart your container.&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FpiHegQDrpchtLjvX3o3e%2Flicensekey.jpg?alt=media&#x26;token=3836df5c-4555-4296-b317-156c756abc68" alt="" width="563"><figcaption></figcaption></figure>

* **Expired License**\
  The License Key associated with the environment has expired. Verify the expiration date of the license within the [**License Management UI**](license-management).

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F216yRwV7d0VQMrAoU2TK%2Flicenseexpiration.jpg?alt=media&#x26;token=2206ec97-2d6f-4f34-a84e-a758b35a124e" alt="" width="563"><figcaption></figcaption></figure>

#### What happens if the Form.io license is invalid:

* The server will **immediately exit** with a **503 error** which will remove portal and form functionality.&#x20;

### License Utilization Issues

Anytime a server is spun up or a Project is created or accessed in your environment, an outbound ping is sent to the license server, and the utilization is recorded in the License Management UI. Exceeding the allocated utilization can cause license errors, blocking further server deployments and functionality of your Projects/Forms. If this occurs, access the [**License Management UI**](#license-manager-ui) to disable unused utilizations, making licenses available for active servers or projects.

{% hint style="info" %}
The License Management UI serves as a log of server and project utilizations. Deleting or disabling an entry in this UI only updates the log—it **does** **not** shut down or deactivate the actual database, server, or project. If you're shutting down a server, make sure to also disable the corresponding environment in the License Management UI to keep the license usage accurate.

Click the link below to read more\
[**License Utilizations Checks**](../../faq/license-utilization-checks)
{% endhint %}

#### **Is my Project utilization active?**

If you encounter a utilization error when accessing your Project, you may have reached the allocation project limit within your license scope, or your Project status is turned off.&#x20;

`Error accessing project: Project license utilization is disabled`

Follow these steps to review and update your license scope&#x20;

1. Copy your Project ID from the URL endpoint within the browser

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FNFQcs4QDR2hiYcAeNQLK%2Fprojectid.jpg?alt=media&#x26;token=75a6537f-63e8-4e99-b012-25ee910bba3c" alt=""><figcaption></figcaption></figure>

2. Access the [**License Management UI**](#license-manager-ui), click the **Projects** tab
3. Search for the Project ID copied in step 1
4. If the License has available projects within the scope, simply click the **Status** button for the Project and then the **Save Projects License**. Refreshing the Project should resolve the error.&#x20;

{% hint style="info" %}
If the License has reached the maximum Project allocations, (as shown in the sceenshot below - Projects 10/10),  you will need to free up a Project allocation slot.&#x20;
{% endhint %}

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FhRphhpL51j5kApwJLeif%2FProjectTab.jpg?alt=media&#x26;token=beef3943-aecb-44dd-9dbd-02b272a74749" alt=""><figcaption></figcaption></figure>

5. To disable a Project utilization, click the **Status** button of an active project within your License scope and click the **Save Projects License** button

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FhzcXYoh69LrauL0m18gb%2Fdisableprojectallocation.jpg?alt=media&#x26;token=095e19dd-d546-4268-83b7-a71007a9eee4" alt=""><figcaption></figcaption></figure>

6. With the additional Project allocation available, toggle the **Status** button for the Project you want to allocate and click the **Save Projects Licenses** button

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FBRN4J8P5YfDyoB6j2F7T%2Fenbableproject.jpg?alt=media&#x26;token=609a03b5-ee02-4048-aa31-ee11d48209ca" alt=""><figcaption></figcaption></figure>

#### **Is my API/PDF Server utilization active?**

If everything on the Project side checks out, ensure your API/PDF Server status is active.  Since many users may have servers running on different environments, it's important to identify the correct environment the issue is occurring. &#x20;

1. Within your environment, input the **status** endpoint within your browser\
   `https://myenvironment.form.io/status`&#x20;
2. Copy the **Environment ID** found in the log

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F88beqdFzHuWucXfu4Wq9%2Fenvironmentstatus.jpg?alt=media&#x26;token=4fa8406f-2716-4c9c-be3c-1605afb0cb0a" alt=""><figcaption></figcaption></figure>

3. Within your License Management, click the **API Server** or **PDF Server** tab
4. Search for the **Environment ID** and determine whether the server **Status** is active

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FMmGaSWEXRJ7GOrIFg7qk%2Fapiserver.jpg?alt=media&#x26;token=f7f163fc-3e22-45a2-8841-f0ec24fcee89" alt=""><figcaption></figcaption></figure>

5. To free up server allocation, disable an active server by clicking the **Status** button and then **Save API Servers Licenses**&#x20;
6. Click the **Status** button for the Server you wish to activate and then **Save API Servers Licenses**&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FLnB2nLDz9roe9wxWuTS7%2Factivateapiserver.jpg?alt=media&#x26;token=3c18b3ed-7a52-49e8-b89c-a940d84d0dd2" alt=""><figcaption></figcaption></figure>

#### **Checking Server Logs**

Another avenue for troubleshooting is reviewing your container logs. These logs will often give you detailed information on what server is failing and the ID associated with the environment. This information can then be used within the License Management UI to determine the Server or Project that is consuming the utilizations.&#x20;

The following showcases the same workflow example detailed in the [**Is my API/PDF Server Active?**](#is-my-api-pdf-server-active) section, only this time, the errors will be examined from the server log perspective.&#x20;

1. Review your server logs and observe any **license validation errors**
2. Take note of the **Environment ID** within the validation error

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F4w2JtJaEjwA3n222N4RC%2Fsererlogs.jpg?alt=media&#x26;token=f90bd8d0-49d3-4a73-8981-95bb970c5eac" alt=""><figcaption></figcaption></figure>

2. Within your License Management, click the **API Server** or **PDF Server** tab
3. Search for the **Environment ID** and determine whether the server **Status** is active

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FN718qzNrgmyuFXqZpJBI%2Fapiserver.jpg?alt=media&#x26;token=8a77a573-f205-4fb3-9ee9-0401484da30c" alt=""><figcaption></figcaption></figure>

4. Free up a utilization for an active server by clicking the **Status** button and then **Save API Servers Licenses**&#x20;
5. Within the **API Server** tab of your License Management UI, click the **Status** button for the Server you wish to activate and then **Save API Servers Licenses**&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2Fp7IL4NcpFWbXCLlblYtB%2Factivateapiserver.jpg?alt=media&#x26;token=7420aa2e-ef47-4574-b188-210bc5cc2d3b" alt=""><figcaption></figcaption></figure>

6. With an additional API Server allocation available, you should be able to **restart** your **Container** with success.&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2Fp3Ww1bEIUwxfFp8nzidz%2Fcontainerlogsuccess.jpg?alt=media&#x26;token=57c9b34c-81f0-422b-8438-639af07c16b0" alt="" width="563"><figcaption></figcaption></figure>



[^1]: Utilizations are the available usage of the features included in the license. For example, a license could have 3 utilization slots for an API Server.&#x20;

[^2]: A User with permissions to access and modify License Utilizations
