Pdftools SDK license management

Learn how to manage the Pdftools SDK license keys. The information on this page applies to legacy and page credit licenses.

Product documentation

For information about using the Pdftools SDK, review Pdftools SDK documentation.

Request trial or full license

You can use the Pdftools SDK and the Pdftools SDK Shell Tool without a license key with watermarked results. To get a full license and remove the watermarks, follow these steps:

Sign up or log in to the Pdftools Portal.
Click Contact sales button.
Fill in the required details.
Click Submit.

Find the license key

To find and copy a license key:

Sign up or log in to the Pdftools Portal.
On the Products page, next to the Pdftools SDK, click Get started or See product.
Find your license key in the License keys section, and then click Copy .

Use the license key in the same format as you copied it. Include the less-than (<) and greater-than (>) signs.

Trial license overview

You can use the same license key for the Pdftools SDK, Pdftools Shell Tool, and Toolbox add-on. The Pdftools SDK and Pdftools SDK Shell Tool don’t require a trial license key, but the Toolbox add-on requires it.

SDK	Can be used without license	Use with trial license	Use with full license
Pdftools SDK	Yes, adds watermark.	Adds watermark.	No watermark.
Pdftools SDK Shell Tool	Yes, adds watermark.	Adds watermark.	No watermark.
Toolbox add-on	No, processing fails.	Adds watermark.	No watermark.

Licensing credit count

Page credit-based pricing charges a page credit for each operation performed on a document page.

A page credit is used for:

Each page of a document.
Each operation applied to that page.

Review the following table for more information about the credit count in the Pdftools SDK and Pdftools SDK Shell Tool for specific operations:

Operation	Page credits used
Archive PDF/A-1	2
Archive PDF/A-2	2
Archive PDF/A-3	2
Compress and optimize	1
Convert	1
Embed e-invoice	1
Extract	1
Merge and split PDFs	1
Archive TIFF	1
Sign and secure	1
Validate	1

Only PDF to PDF/A conversion is charged at 2 page credits per operation; all other operations cost 1 page credit.

Operations

An operation is any action performed on a document using the Pdftools SDK and Pdftools SDK Shell Tool. Common operations include:

File conversions: Converting files to or from PDF (for example, TIFF to PDF, PDF to image).
Compressing or optimizing PDFs.
Merging files or extracting pages, adding signatures, encrypting, or annotating PDFs.

Each time you apply an operation to one or more pages, page credits are charged based on each page affected by the operation. Pages that are not affected by the operation are not charged. For example, if you have a 10-page document and only use the extract operation on five pages, only 5 page credits are used.

Calculating credits

To determine how many page credits you’ll need for your tasks using the Pdftools SDK, follow this formula:

Number of pages x number of operations = total page credits used

For example:

Three-page PDF, one operation: Converting a three-page TIFF to PDF requires 3 page credits (1 per page).
Three-page PDF, two operations: Converting a three-page PDF and then compressing it requires 6 page credits (3 pages x 2 operations).
Three-page PDF, PDF/A conversion: Converting a three-page PDF to PDF/A requires 6 page credits (3 pages x 2 page credits).

Page credits are calculated for every operation applied. If multiple actions are performed on a file, page credits are consumed for each operation. For example:

Four pages, one operation: Signing four individual pages of PDF costs 4 page credits (4 pages x 1 operation).
Four pages, two operations: Converting and compressing a four-page PDF costs 8 page credits (4 pages x 2 operations).
Four pages, three operations: Converting, compressing, and adding a watermark to a four-page PDF costs 12 page credits (4 pages x 3 operations).

License key validation

License keys are validated using the Pdftools Licensing Service. The SDK connects to the Pdftools Licensing Service to provide usage information and retrieve new licensing parameters after processing a document.

The Pdftools Licensing Service collects the following statistics and information:

License number
Pdftools SDK functions used and the number of pages processed

For information on managing your license key with the Pdftools Licensing Service, see Pdftools Licensing Service.

Initialize the Pdftools SDK license

Learn how to use a license key for the Pdftools SDK. Review the appropriate link for your programming language:

Use Pdftools SDK Shell Tool license

Learn how to use the Pdftools SDK Shell Tool license key:

Use of license key

Default license configuration

By default, when the Pdftools SDK is initialized, it attempts to directly connect to the Pdftools Licensing Service. This requires an internet connection to the default licensing service URL:

https://licensing.pdf-tools.com/api/v1/licenses/

caution

By default, if the Pdftools SDK cannot connect to the licensing service URL, the SDK initialization fails.

Use the Licensing Gateway

Use the Licensing Gateway Service (LGS) if the Pdftools SDK needs to operate without a direct connection to the Pdftools Licensing Service.

To configure the SDK to use the Licensing Gateway Service, set the LicensingService property of the Sdk class before calling Sdk.Initialize.

C
Java
.NET
Python

int main(int argc, char* argv[])
{
    // Initialize the library
    PdfTools_Initialize();

    // Set the URL to the Licensing Gateway Service.
    if (!PdfTools_Sdk_SetLicensingService("http://my.gateway.com:9999"))
    {
        // Handle error
        return 1;
    }

    // Set and check license key. If the license key is not valid, the function returns FALSE.
    if (!PdfTools_Sdk_Initialize("$LicenseKey$", NULL))
    {
        // Handle error
        return 1;
    }

public static void main(String[] args)
{
    try
    {
        // Set the URL to the Licensing Gateway Service.
        Sdk.setLicensingService(new java.net.URI("http://my.gateway.com:9999"));

        // Set and check license key. If the license key is not valid, an exception is thrown.
        Sdk.initialize("$LicenseKey$");

static void Main(string[] args)
{
    try
    {
        // Set the URL to the Licensing Gateway Service.
        Sdk.LicensingService = new Uri("http://my.gateway.com:9999");

        // Set and check license key. If the license key is not valid, an exception is thrown.
        Sdk.Initialize("$LicenseKey$");

from pdftools_sdk.sdk import Sdk

try:
    # Set the URL to the Licensing Gateway Service.
    Sdk.set_licensing_service("http://my.gateway.com:9999")

    # Set and check license key. If the license key is not valid, an exception is raised.
    Sdk.initialize("$LicenseKey$")

note

More information about the LicensingService property is available in the SDK API references for C, .NET, Java, and Python.

Check the license status

To review the remaining page credits, license expiration, and license validity in general, use one of the following approaches:

In the Pdftools Portal. For more information, review View page credits consumption in the Pdftools Portal.
To check the license status programmatically, refer to Check the license status programmatically.

View page credits consumption in the Pdftools Portal

Log in to the Pdftools Portal.
In the Products tab, click See product next to the Pdftools SDK.
Find your page credits usage in a specific section that lists your license key.

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

Check the license status programmatically

When the Pdftools SDK is successfully initialized, check your license status by accessing the LicenseInfoSnapshot property of the SDK class. This property provides the following information about the current license:

IsValid: License validity.
ExpirationDate: The date and time when the license expires.
RemainingPages: The number of pages available for processing based on the license agreement.
Overconsumption: The number of pages available for processing before the SDK stops functioning.

If the RemainingPages value reaches zero, the Pdftools SDK provides a limited number of Overconsumption pages. The Overconsumption pages provide you with the opportunity to update your license agreement without disrupting your business processes.

caution

If both the RemainingPages and Overconsumption values reach zero, the Pdftools SDK stops functioning until the licensing service is updated with new license information.

note

More information about the LicenseInfoSnapshot property is available in the Pdftools SDK API references for C, Java, .NET, and Python.

Configure proxy

Configure proxy settings when you need all your HTTPS and HTTP communication to go through one central point in your network. If your implementation of the Pdftools SDK requires connectivity to services external to your network that are not directly reachable by your application (for example, time-stamp authority (TSA), or you are using page credit license key with configured LGS), or the SDK is operating in an environment where direct internet access is restricted, such as behind a firewall.

Configure proxy if:

You have a central point in your network through which you wire all your HTTPS and HTTP communication.
If you have a page credit license key and a central point in your network through which you wire all your HTTPS and HTTP communication.

Condition	Proxy Required?	Notes
All HTTPS/HTTP communication must go through a central network point	Yes	General requirement when routing traffic through a proxy.
SDK must connect to external services not directly reachable (for example, TSA, LGS)	Yes	Includes scenarios behind firewalls or restrictive environments.
Page credit-based license key and centralized HTTPS/HTTP routing	Yes	LGS or credit license usage behind a proxy requires configuration.
Trial license key in use	No	Proxy isn’t required even if centralized routing exists.
Page credit-based license key without the need for centralized HTTPS/HTTP routing	No	Proxy isn’t required if the app can directly access the internet.

For specific steps to enable the proxy server, review the following resources depending on your use case:

Digital signing proxy configuration, review Using a proxy server.
For other use cases, review the following Procedure.

Procedure

To configure a proxy, assign the PdfTools.Sdk class a Proxy server URI that the SDK will use for all HTTP and HTTPS communications with remote services. Follow these steps to configure a proxy:

In your application code, set the proxy before initializing the SDK:
```
http[s]://[USER[:PASSWORD]@]HOST[:PORT]
```
Where:
- http/https: Protocol for connection to proxy.
- USER:PASSWORD (optional): Credentials for connection to proxy (basic authorization).
- HOST: Hostname of proxy.
- PORT: Port for connection to proxy.
For example, in C#:
```
Sdk.Proxy = new Uri("https://myuser:mypassword@proxy.example.com:8080");
```
After setting the proxy configuration, initialize the SDK using your license key. It is important to call the initialization after the proxy configuration. For more information about the Pdftools SDK initialization, review Initialize the Pdftools SDK license.

In the Pdftools SDK Shell Tool, you can configure the proxy using the -proxy URL option. In this option, replace the URL with your actual proxy URL.

Notes

You can also find information about the proxy configuration in the API references, for example Sdk.Proxy Property in the .NET API documentation.

Request trial or full license​

Find the license key​

Trial license overview​

Licensing credit count​

Operations​

Calculating credits​

License key validation​

Initialize the Pdftools SDK license​

Use Pdftools SDK Shell Tool license​

Default license configuration​

Use the Licensing Gateway​

Check the license status​

View page credits consumption in the Pdftools Portal​

Check the license status programmatically​

Configure proxy​

Procedure​