Skip to main content

Conversion Service licensing

Learn how to activate and configure license keys for the Conversion Service.

Product documentation

For information about using the Conversion Service, review Conversion Service documentation.

This page includes details about one of the Pdftools products. For a general overview of different licenses of Pdftools products, see Licenses of Pdftools products.

Trial license​

Conversion Service 6.12 and later automatically registers a built-in trial license on every fresh installation, on Windows, in Docker, and on Linux. The service starts fully licensed, so you don’t need a license key to try Conversion Service. The trial license adds a watermark to converted files and doesn’t expire.

In the Conversion Service Configurator, the trial license appears as TRIAL-LICENSE in the Key field on the License tab.

Docker

In Docker, the container registers the trial license only when you don’t pass a license key with the LICENSEKEY or LICENSEKEY_FILE environment variable.

To convert files without a watermark, replace the trial license with a full license key.

Request full license​

tip

The built-in trial license lets you try Conversion Service at no cost. To convert files without a watermark, request a full license key.

To request a full license key, follow these steps:

  1. Sign up or log in to the Pdftools Portal.
  2. On the Products page, next to the Conversion Service, click Request license.
    Screenshot of the Pdftools Portal's product page.
  3. On the Contact us window, fill in the requested fields, and then click Submit.

After you receive your full license key, replace the trial license with it. For more details, review Add or remove a license key.

Find the Conversion Service license key​

To find and copy a license key:

  1. Sign up or log in to the Pdftools Portal.
  2. On the Products page, next to the Conversion Service, click Get started or See product.
    Screenshot of the Pdftools Portal's product page.
  3. Next to the Conversion Service Trial or Active, click Click to copy .
    Screenshot of the Pdftools Portal's Conversion Service trial license key details.

Use the Licensing Gateway Service​

Conversion Service validates license keys either directly or through the Licensing Gateway Service (LGS). The license.useLgs setting in the appsettings.json configuration file controls whether the service uses the LGS:

  • license.useLgs: false: The service validates license keys directly against the Pdftools Licensing Service at https://licensing.pdf-tools.com. This is online only. Fresh installations of Conversion Service 6.12 and later use this setting by default.
  • license.useLgs: true: The service routes licensing through the LGS at the address configured in license.licensingUrl. The LGS then runs in Connected mode or Full offline mode (review the Licensing Gateway Service section). Installations upgraded from earlier versions keep this setting: the configuration updater automatically sets license.useLgs: true during the upgrade, so existing LGS-based deployments behave unchanged.

In Docker, override the setting with the LICENSE__USELGS environment variable set to true or false.

Offline licensing requires the LGS

Validating license keys directly is online only. The Full offline mode and the offline activation workflow are available only through the LGS.

Enable or disable the LGS in the Configurator​

To enable or disable the LGS on Windows systems:

  1. In the Conversion Service Configurator, click the License tab.

  2. Enable or disable the Use License Gateway Service toggle.

    The status text next to the toggle shows whether the LGS is enabled or disabled. For legacy and OEM licenses that don’t use the LGS, the toggle is unavailable and the status shows Not used.

  3. Click Save or Save & Restart.

When the toggle is disabled, the Configurator hides the LGS-specific elements: the License Gateway Address field, the licensing gateway mode and status, the sync (borrow-time) status, and the Reactivate button. License consumption and the license end date are still displayed through the direct connection.

Proxy for direct license key validation​

When the service validates license keys directly (license.useLgs: false), the service-wide proxy setting (service.proxy in appsettings.json or the -proxy option) applies to the communication with the Pdftools Licensing Service. Credentials embedded in the proxy URL are supported, for example, http://USER:PASSWORD@PROXY_ADDRESS:PORT.

Add or remove a license key​

How the service validates a license key depends on whether it uses the LGS. For more information, review Use the Licensing Gateway Service.

  • With license.useLgs: false, adding a license key validates it online against the Pdftools Licensing Service and stores it locally, without an LGS registration. Removing a license key is a local-only operation. Saving the configuration doesn’t require a reachable LGS.
  • With license.useLgs: true, the LGS validates the license key and requires an internet connection. Read the Licensing Gateway Service section for more information.

The csconfig license add and csconfig license remove CLI commands follow the same setting. The steps to add or remove a key depend on your platform.

Windows​

To add a license key:

  1. In the Conversion Service Configurator, click the License tab.
  2. Paste the license key into the Key field, and then click Add.

To remove a license key:

  1. In the Conversion Service Configurator, click License tab.
  2. Under the License Information section, next to the Key field, click Remove.

Adding a full license key automatically replaces the built-in trial license. You don’t need to remove the trial license first.

Docker​

Review the following links for information about the Conversion Service license key management in Docker:

Linux​

On Linux, the DEB and RPM packages don’t include the LGS. If you configure Conversion Service to use the LGS (license.useLgs: true), install the LGS snap, add your license key to it, and then point Conversion Service at the LGS.

To set up licensing, follow these steps:

  1. Install the License Gateway Service snap. Refer to Install the LGS.
  2. Add your license key to the LGS: 
    sudo licgwy.ptl add LICENSE_KEY_VALUE
  3. Confirm that the LGS synced with the licensing server: 
    sudo licgwy.ptl status
  4. Point Conversion Service at the LGS by adding the following variables to its environment file: 
    sudo tee -a /etc/pdftools/conversion-service/env >/dev/null <<EOF
    LICENSE__USELGS=true
    LICENSEKEY=LICENSE_KEY_VALUE
    LICENSINGSERVICE=http://localhost:9999
    EOF
  5. Restart Conversion Service to apply the change: 
    sudo systemctl restart pdftools-conversion-service

Replace LICENSE_KEY_VALUE in both commands with your Conversion Service license key.

caution

LICENSE__USELGS, LICENSEKEY, and LICENSINGSERVICE are all required. LICENSE__USELGS=true routes licensing through the LGS; without it, the service validates the key directly and ignores LICENSINGSERVICE. LICENSEKEY tells the service which key to broker, and LICENSINGSERVICE is the LGS URL. In versions earlier than 6.12.0, Conversion Service fails to start without a license key: the service logs an Unable to start error, and the /conversion/v1.0/rest endpoint returns HTTP 500. In version 6.12.0 and later, fresh installations start with the built-in trial license.

To use an LGS that runs on another machine, such as a shared LGS host or an existing Windows LGS, set LICENSINGSERVICE to http://LGS_HOST:9999. Replace LGS_HOST with the host name or IP address of that machine.

Licensing credit count​

Conversion Service charges page credits based on the number of the pages a job processes, rather than the number of pages in the input documents. The processed page count for a document is determined by the highest page count reported by any processing step. This includes pages from attached and embedded documents, as well as the total number of pages from the input documents that are merged into a single output. If a job does not process any pages, no page credits are consumed.

The selected workflow sets the price of a processed page:

WorkflowPage credits per page
Archive as PDF/A-12
Archive as PDF/A-22
Archive as PDF/A-32
Archive as TIFF1
Convert to PDF1
Convert to XML1
Create Dossier PDF1, 2, or free (review Create Dossier PDF page credits)
Extract XML from PDF1
Prepare Invoice PDF2
Sign PDF1

For what each workflow does, review Workflows.

Enabling PDF/UA conversion doubles the page credits for a job: the Convert to PDF workflow costs 2 page credits per page instead of 1, and Archive as PDF/A-2 costs 4 instead of 2. For more details, review PDF/UA accessibility.

Create Dossier PDF page credits​

info

The Create Dossier PDF workflow lets you assemble several PDF documents into a single dossier with extended functionality, such as a title page and table of contents.

The number of page credits charged for the Create Dossier PDF workflow depends on the selected preprocessing workflow:

  • Any Archive as PDF/A workflow (Archive as PDF/A-1, Archive as PDF/A-2, Archive as PDF/A-3) costs two page credits per page.
  • The Convert to PDF workflow costs one page credit per page.
  • If you don’t select a preprocessing step, assembling a dossier costs no page credits.

Remaining page credit count​

To review the remaining page credits in your license usage quote, you can review your license usage:

If you are using a version of the Conversion Service prior to 6.6.0, contact the Pdftools sales team through the Contact page to get information about the remaining page credit count.

View page credits consumption in the Pdftools Portal​

  1. Log in to the Pdftools Portal.
  2. In the Products tab, click See product next to the Conversion Service.
  3. Find your page credits usage in a specific section that lists your license key.
    Screenshot of the Pdftools Portal with the license consumption details.

On this page, you can review your total number of page credits, number of used credits, license key expiration, and more.

View page credits consumption in the Conversion Service Configurator​

  1. In the Conversion Service Configurator, open the License tab.
  2. Review the percentage of used page credits in the Properties section.
    Screenshot of the Conversion Service Configurator with the license consumption details.

Licensing Gateway Service​

When the service is configured to use the LGS (license.useLgs: true), Conversion Service uses the Licensing Gateway Service (LGS) to activate and use a license key or to report the number of used page credits to Pdftools. The LGS connects to the Pdftools Licensing Service to validate the installed license key and transmit the number of processed pages. Since version 4.7 of Conversion Service, the LGS is installed locally with Conversion Service on Microsoft Windows systems. For more information about enabling the LGS, review Use the Licensing Gateway Service.

Use the LGS to share one license key across multiple Conversion Service instances or to run Conversion Service fully offline.

Licensing Gateway Service configuration with a single machine

To configure the firewall service correctly, note that the LGS connects through port 443 (SSL) to the Pdftools Licensing Service hosted at https://licensing.pdf-tools.com/.

Privacy

Pdftools does not receive information about documents and data processed by the Conversion Service other than the hostname and the number of processed pages. At Pdftools, we highly value our customers’ privacy.

Internet access​

The LGS requires an internet connection. The Conversion Service uses LGS to add or remove a license key, or to report the number of used page credits to Pdftools.

If you lose the internet connection, the license key remains active for:

  • Seven days - Professional and Business plan
  • 30 days - Enterprise plan

You are prompted with a configuration error if the gateway refuses to consume page credits due to an invalid license or lack of internet connection. Details about the error are in the Conversion Service log. For more information, review Troubleshooting section.

Fully offline access

Contact the Pdftools Customer Success team to discuss fully offline access to the Conversion Service. This option is available for the Enterprise plan users.

Manage multiple Conversion Service installations​

All your Conversion Service instances can use the same license key activated in one LGS. You can use the same LGS as the one that is preinstalled by default with the Conversion Service, or you can install the LGS separately without the Conversion Service. The system that sends the usage data must have an internet connection. In a nutshell, to have multiple systems running the Conversion Service using a single license key:

  • Change the LGS address to the address of a system that sends the usage data.
  • The system that sends usage data needs to maintain an internet connection.
    • This system needs to have the LGS installed.
      You can install the LGS:
      • Automatically with the Conversion Service.
      • Separately without the Conversion Service.

For example, there are computers A, B, and C in the local network. Computers B and C send usage data to computer A. A then sends data to Pdftools. To create this setup:

  • Computer A needs to have the LGS installed and configured.
  • Computers B and C need to have the local network address of A added in the Conversion Service Configurator.
Multiple license keys

It is possible but not required to activate different instances with multiple license keys. Multiple license keys can be issued under specific circumstances. When Windows and Docker-based Conversion Service is running simultaneously, or if you use an older licensing model based on a number of cores. For more details, review Legacy core-based license key section.

Multiple Systems

For specific steps, configure the LGS as described in the following Prerequisites and Change the Licensing Gateway Service address in the Conversion Service sections.

Prerequisites​

Ensure you have an LGS set up and that your license key is activated. If you choose to install the LGS separately without the Conversion Service, make sure that this system has an internet connection to communicate with the Pdftools Licensing Service. For detailed instructions on how to install and interact with the LGS, review Install the LGS.

Change the Licensing Gateway Service address in the Conversion Service​

For each Conversion Service instance, add the address of the system that hosts the Licensing Gateway Service (LGS), which also maintains the internet connection with Pdftools.

note

If you activated a license key before, you must remove it first. To remove the license key:

  1. In the Conversion Service Configurator, go to the License tab.
  2. Copy the license key from the Key field.
  3. Click Remove, and then OK.

Configure the LGS address by the following steps:

  1. In the Conversion Service Configurator, go to the License tab.

    License tab in the Configurator

  2. In Configuration, change the License Gateway Address field to the specific computer address in your network that has LGS installed.

  3. Click Save or Save & Restart.

  4. Paste the license key to the Key field, and then click Add.

Activate Conversion Service license key in Docker

If you are using Conversion Service in Docker, set the LICENSE__USELGS environment variable to true and change the address of the Licensing Gateway Service using the environment variable LICENSINGSERVICE. Find more details in Manage license keys, in the Conversion Service documentation.

Full offline mode license activation​

Use the Conversion Service fully offline with valid license keys for at least three months or more, depending on your license.

Full offline mode requires routing licensing through the LGS (license.useLgs: true). For more information, review Use the Licensing Gateway Service. Before configuring offline mode, enable the Use License Gateway Service toggle on the License tab of the Conversion Service Configurator.

Configure offline mode​

Configure the Licensing Gateway Service (LGS) for offline use:

  1. Locate the LGS configuration file appsettings.json. The configuration file is in the installation folder, for example: 
    C:\Program Files\Pdftools\Licensing Gateway Service\appsettings.json
  2. Update the configuration file so that the IsOfflineMode property is set to true. Example configuration file: 
    {
      "LicensingServicePortNumber": 9999,
      "LogFilePath": "C:/logs/pdftls/log.txt",
      "LogRetentionDays": 7,
      "IsOfflineMode": true
    }
  3. Restart the Licensing Gateway Service.
  4. Go to the Conversion Service Configurator > License tab.
  5. Click Refresh button next to the Licensing Gateway Mode field, or restart the Configurator.
    Conversion Service Configurator showing Full Offline mode in the Licensing Gateway Mode field.
  6. Verify that the Licensing Gateway Mode displays Full Offline.

Add license key​

To add a license key in full offline mode:

  1. In the Conversion Service Configurator, select the License tab, enter your license key in the Key field, and then click Add.

    Conversion Service Configurator License tab with the Add button.

  2. Optional: In the Activation Wizard, you can change the pre-populated Computer Name field with another machine name.

    Offline Activation Wizard showing the Computer Name field.

  3. Click Generate Token. The generated token is valid for 24 hours.

    Activation Wizard with the generated token displayed, showing 24-hour validity notice.

  4. Click Copy button to copy the token, and then click Next.

    Activation Wizard showing the Copied confirmation after copying the token.

    The Activation Wizard displays the guidance for the next steps.

    Configurator Activation Wizard showing instructions on how to navigate to the Pdftools Portal.

  5. Optional: If the machine running the Configurator doesn’t have internet access, transfer the token to a machine that does.

  6. Open the Pdftools Portal in a web browser.

  7. Select the Activate tab, and then paste the token into the field marked as Insert your token here.

    Pdftools Portal with the activation token pasted.

  8. Click Activate.

    Pdftools Portal after clicking Activate.

  9. Click Copy to copy the response token.

    Pdftools Portal showing the response token to copy.

  10. Optional: If you accessed the Portal from a different machine, transfer the response token back to the machine running the Configurator.

  11. In the Configurator, click Next.

  12. Press Ctrl + v or click the paste icon to paste the token into the text field.

    Activation Wizard with the response token pasted.

  13. Click Apply.

The license is added. The Configurator displays the License Expiration Date and Token Validity.

Configurator showing the successfully added license with expiration date and token validity.
License expiration and token validity

The License tab displays two dates related to the offline activation:

  • License expiration - The date when the license key expires.
  • Sync - Number of days for which offline activation is valid.

Both of these values must be valid for the license to work in the full offline mode. These values are independent. Your license key can expire before or after the full offline mode activation period. To extend the token validity period, review Reactivate license key.

Reactivate license key​

To extend the token validity for a license key in the full offline mode, follow these steps:

  1. In the Conversion Service Configurator, select the License tab.
  2. Click Reactivate.
  3. Follow the same steps as described in section Add license key

Remove license key​

To remove a license key in full offline mode:

  1. In the Conversion Service Configurator, select the License tab, and then click Remove. The Offline Deactivation Wizard opens.
    Offline Deactivation Wizard showing the Computer Name field.
  2. Click Generate Token. The generated token is valid for 24 hours.
    Deactivation Wizard with the generated token displayed, showing 24-hour validity notice.
  3. Optional: Change the pre-populated Computer Name field to another machine name.
  4. Click Copy to copy the token.
    Deactivation Wizard showing the Copied confirmation after copying the token.
  5. Click Next.
    Deactivation Wizard, showing instructions to navigate to the Pdftools Portal.
  6. Optional: If the machine running the Configurator doesn’t have internet access, transfer the token to a machine that does.
  7. Open the Pdftools Portal in a web browser.
  8. Switch to the Deactivate tab, and then paste the token into the field marked as Insert your token here.
    Pdftools Portal Deactivate tab with the deactivation token pasted.
  9. Click Deactivate.
  10. Click Copy to copy the response token.
    Pdftools Portal after clicking Deactivate.
  11. Optional: If you accessed the Portal from a different machine, transfer the response token back to the machine running the Configurator.
  12. In the Configurator, click Next.
  13. Press Ctrl + v or click the paste icon to paste the token into the text box.
    Pdftools Portal showing the deactivation response token to copy.
  14. Click Apply.
    Deactivation Wizard with the response token pasted.

The license key is removed. The Configurator displays only a limited number of tabs (Support Request, License, and About).

Configurator showing the license has been removed.

Legacy core-based license key​

License keys issued before September 2023 use a core-based license. With a core-based license, you can manage the license keys with the legacy License Manager application. There are different options depending on the version of the Conversion Service:

  • Conversion Service version 4.6 or earlier: Use the legacy License Manager to activate and deactivate core-based license keys.
  • Conversion Service version 4.7 or higher: You can use both the License tab in the Conversion Service Configurator for the usage-based licensing model or the legacy Licensing Manager to activate and deactivate core-based license keys.
  • Conversion Service version 5.2 or higher: You can use only the License tab in the Conversion Service Configurator for the usage-based licensing model to activate, update, or deactivate core-based license keys.

Offline usage for legacy core-based licenses​

The following actions require internet access:

  • License key activation
  • License key update
  • License key deactivation

See the next sections for more information about offline license key activation, update, and deactivation for the legacy core-based licenses.

Offline license key activation​

To activate a license key without internet access:

  1. In the Conversion Service Configurator, select the License tab.
  2. Paste your license key in the Key field, and then click Add.
  3. If you are offline, a window appears with a prompt: You’re offline. Follow the steps to activate a license key offline:
  4. Follow the steps as documented within the Conversion Service Configurator.

Offline license key update​

To update a license key without internet access:

  1. In the Conversion Service Configurator, select the License tab.
  2. Click Update.
  3. If you are offline, a window appears with a prompt: You’re offline. Follow the steps to activate a license key offline:
  4. Follow the steps as documented within the Conversion Service Configurator.

Offline license key deactivation​

To deactivate a license key without internet access:

  1. In the Conversion Service Configurator, select the License tab.
  2. Click Remove.
  3. If you are offline, a window appears with a prompt: You’re offline. Follow the steps to activate a license key offline:
  4. Follow the steps as documented within the Conversion Service Configurator.

Troubleshooting​

You may encounter problems when adding or using a license. See the following sections for the most common errors.

Configuration errors​

During configuration, you can encounter warnings and errors inside the Conversion Service Configurator. These errors and warnings can also prompt you with a resolution of your issue.

Unable to add license key / License key could not be removed

Adding a page-based license key requires an internet connection whether or not the service uses the LGS. With license.useLgs: false, the service must reach the Pdftools Licensing Service at https://licensing.pdf-tools.com. With license.useLgs: true, the License Gateway requires the internet connection to add and remove a license key.

Activation Failed / License key could not be deactivated

Usage-based licensing: When you activate a license key in the LGS, it is linked to the machine where you activated it. If you install LGS on another machine, deactivate the license key so you can activate it again in the LGS. For more information, review Deactivate a license key.

Core-based licenses: Most core-based licenses must be activated before they can be used and deactivated before they can be removed. The activation and deactivation process requires an internet connection. If your system is running offline, review Offline usage documentation.

License validation or consumption errors​

Some of the warnings and errors that can be encountered during regular use of the service.

License consumption failed (InvalidConfiguration)

There was an error in the consumption of the license page credits. There are several possible reasons for such an error. Use the Conversion Service Configurator to view the current license status and if there are any errors.

Service not available due to a license issue

The validation of the current license failed. Please use the Conversion Service Configurator to view the current license status.