Skip to main content
Skip table of contents

Installing the iText license key and license key library for Java and .NET

Thank you for your interest in our PDF library, we hope you will enjoy using our product and share your experiences with us and the iText community. We will walk you through the installation process of the iText license key and library.

If you are interested in getting support from our in-house developers and/or a license key for commercial iText products, you will need to acquire a commercial license.

NOTE: These instructions apply to both iText 5/iTextSharp and its successor iText Core.

Important!

As of the release of iText 7.2, the old licensing system was replaced by a new Unified Licensing Mechanism, which allows volume users to more easily check their usage and extended the event counting capabilities. This replaces the old itext-licensekey and itext-licensekey-volume dependencies with the new licensing-base and licensing-remote dependencies, and the version number for the licensing libraries was increased from version 3.x to 4.x. In addition, it replaces the old XML license file with a new one in JSON format.

Simply put, if your license key file is an XML file you should follow the instructions marked iText 7.1.x in this installation guide. However, if you have a JSON license key file, see the instructions for iText 7.2.x and newer.

Introduction

  • To use iText’s proprietary libraries you need to install a valid license and the license key library. Get a valid license.

  • Loading a license will display a producer line on PDFs, which you can check to ensure you are using the correct license type. The producer line is (in the case of iText 7) “iText ® 7.x.y © 2000—2021 iText Group NV”, followed by a suffix. This suffix is:

    • “AGPL version”, when not using the licensing library or when using an invalid/expired license;

    • “Trial version”, when using the licensing library and a valid trial license;

    • “Licensed version”, when using the licensing library and a valid license.

Pre-installation

The requirements to install the license and the license key library are as follows:

  • Obtain a valid license. For iText’s proprietary libraries a valid (trial or commercial) license is required.

  • After accepting the terms of use, download the license file through the portal by selecting it and clicking on 'Download Selected Keys'. It will download in a zip file containing a JSON file (or XML file for iText 7.1.18 and older) with information about who you are, and a key that allows you to use the software.

  • The file name for the license key file will probably be the same as your actual license key, though you can rename it for convenience. Just make sure when you call it in your code you use the correct file name!  

  • To be able to load this license file you need an additional library—the license key library. If you have previously downloaded the license key library, please make sure you have the latest one applicable to your version of iText. See Which version of the license key library should I use? for more details.

  • License keys in JSON format will work for iText Suite version 7.2 and newer. XML license keys are for iText Suite 7.1.18 and older (and iText 5/iTextSharp).

Library installation and loading the license key

You'll need two things:

  • the license key file, and 

  • the latest version of the license key library.  For iText 7.2 and newer, this is version 4.x.x of the licensing-base library. For iText 7.1.18 and older, or for iText 5.5.13 (or newer) this is version 3.x.x of the itext-licensekey library.

Download the license key library:

NOTE: For iText versions 5.5.13 and newer, we changed to use the same license key version as for iText Core. Download the license key library from the iText 7.1.x links below for Java or .NET.

For iText 7.2.x and newer

Java

The license key library (licensing-base-x.y.z.jar) needs to be on the classpath. It can be downloaded from our repository.

You can also use Maven to resolve this dependency. To do so, add the iText Artifactory server, https://repo.itextsupport.com/releases, as an additional repository in the repositories section of your pom.xml, as described in the Maven documentation. Then you can add the following dependency to your dependencies:

XML 
<properties>
       <itext.licensekey.version>$release-license-base-variable</itext.licensekey.version>
</properties>

<dependencies>
  <dependency>
    <groupId>com.itextpdf.licensing</groupId>
    <artifactId>licensing-base</artifactId>
    <version>${itext.licensekey.version}</version>
  </dependency>
</dependencies>

.NET

For iText 7.1.x

Java

The license key library (itext-licensekey-x.y.z.jar) needs to be on the classpath. It can be downloaded from our repository.

You can also use Maven to resolve this dependency. To do so, add the iText Artifactory server, https://repo.itextsupport.com/releases, as an additional repository in the repositories section of your pom.xml, as described in the Maven documentation. Then you can add the following dependency to your dependencies:

XML 
<properties>
       <itext.licensekey.version>$release-license-variable</itext.licensekey.version>
</properties>

<dependencies>
  <dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>itext-licensekey</artifactId>
    <version>${itext.licensekey.version}</version>
  </dependency>
</dependencies>

.NET

Enable the automated monitoring of volume licenses (Capacity Rental License)

With the release of version 3.0.0 of the license key library, we introduced a volume based counting mechanism. The mechanism works with an event system through which iText and its add-ons will send events.

When the volume license key file has been loaded, the statistics concerning usage will be sent to our servers. This means the machine that runs your application needs an active Internet connection. The information collected is consistent with the terms of the SLA and is restricted to the quantity of PDF files generated, modified, adapted, stamped, filled in, inspected or otherwise processed.

For more information, click here to read our guide showing you how to enable the automated monitoring of volume licenses (Capacity Rental License).

Load the license key

The license key file needs to be loaded before calling the proprietary code. This is done using the static method of the LicenseKey class. Note that once a license key has been loaded it is active for the entire CLR/JVM runtime, if you have multiple CLRs or JVMs accessing the same license key you should provide a copy of the license key for each CLR/JVM.

Java

The license key library (licensing-base-x.y.z.jar for iText 7.2 and newer or itext-licensekey-x.y.z.jar for iText 7.1.18 and older) needs to be in the classpath.

.NET

The license key library (itext.licensing.base.dll for iText 7.2 and newer or itextsharp.licensekey.dll for iText 7.1.18 and older) needs to be added as a reference to your project.

For iText 7.2.x and newer

In the following examples the license key file has been renamed to "itextkey.json" for convenience.

Java

JAVA 
LicenseKey.loadLicenseFile(new File("path/to/itextkey.json"));

.NET

C# 
LicenseKey.LoadLicenseFile(new FileInfo("@path/to/itextkey.json"));

For iText 7.1.x

In the following examples the license key file has been renamed to "itextkey.xml" for convenience.

Java

JAVA 
LicenseKey.loadLicenseFile("path/to/itextkey.xml");

.NET

C# 
LicenseKey.LoadLicenseFile("path/to/itextkey.xml");

NOTE: You'll need to call this line of code before any other iText API call. Not loading the key at startup might result in the producer line having a reference to "AGPL" instead of your company name.

Troubleshooting

Common Error messages

I get a “LicenseKeyException” error message like the following:

Exception in thread "main" com.itextpdf.licensekey.LicenseKeyException: The 'itext-licensekey-volume' library is required for your license type, but it is missing or outdated. Please add or update this library. If you have any questions, contact our support team: https://itextpdf.com/support

You have a Capacity Rental License but the itext-licensekey-volume library could not be found. This is likely due to your project not being correctly set up to enable the automated volume based counting mechanism. See the Volume Counter installation guide for more details.

I get "version mismatch error"

You are most likely combining the wrong library version with your license key.

For iText 7.2 and newer, this is version 4.x.x of the licensing-base library. For iText 7.1.18 and older, or for iText 5.5.13 (or newer) this is version 3.x.x of the itext-licensekey library.

If you are using version 5.5.13 or newer of iText 5/iTextSharp, it uses the same license key version as iText 7.1.x. Download the license key library from the iText 7.1.x link below for Java or .NET.

For older versions of iText 5/iTextSharp use version 1.0.4.

Java

.NET

I get "signature corrupted"

This can mean a few things:

  • The license key file was corrupted during the download. Try downloading it again and loading the newly downloaded file. If the issue persists, contact us so that we can resolve this issue.

  • You changed the contents of your license key. Please revert the license key to its original state. If you want to change the content of the key, please contact our sales department.

I get "product not found"

You are trying to use an add on product without having loaded a license key that contains a valid license for that product. If you bought a license for the add-on, please contact our sales department to rectify this. If you didn't buy a license and you want to try out the add on, you may want to register for a trial license.

I get "The license info of already loaded license doesn't match the new one."

You are most likely trying to load an additional license key containing new add-ons. This can only work if the core information is the same. If it's not the same and it should be, contact us to rectify this issue. If it's not the same, please only use your own license key and don't pass your license keys around.

License key FAQs

How do I check if my key has been loaded correctly?

For the core iText library, the license is only checked when you load it. If you loaded the license key and there was no exception thrown, then it loaded correctly. The add-ons, however, will regularly check the license key. If there is an issue with your license key, the library will throw a LicenseKeyException.

If you want to check the license key manually, you can call the following method:

Java

JAVA 
LicenseKey.scheduledCheck(null);

.NET

C# 
LicenseKey.ScheduledCheck(null);

This will throw a LicenseKeyException when the key is invalid or corrupt.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close