Toolbox add-on license management

Learn how to manage the Toolbox add-on license keys. The information on this page applies to page credit licenses.

Product documentation

For information about using the Toolbox add-on, review Toolbox add-on documentation.

Request a license

The Toolbox add-on requires a trial or full license key. Review the following sections to acquire a trial license or a full license.

Trial license

To try out and evaluate the Toolbox add-on, you can acquire a trial license key for free when you sign up or log in to the Pdftools Portal. For the exact procedure, review Find the license key section.

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.

Full license

To request a full production license key:

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 Toolbox add-on, 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.

Licensing credit count

The Toolbox add-on checks page credit consumption and license validity only during specific operations. It consumes page credits based on:

Adding pages to a document (PageList mutations).
Accessing page content (Page.Content getters).

Each time you add a page to a PageList or retrieve page content, one page credit is consumed. As a result, creating pages, setting metadata, and adding text or images to a page before adding it to the document does not consume page credits.

Page mutations

Adding pages to a PageList consumes credits in :

Java: PageList.add* methods
Python: PageList.insert, PageList.append, PageList.extend methods
.NET: Document.Add* methods, CopyTo* methods
C: PtxPdf_PageList_Add* functions

Content getters

Accessing page content consumes credits:

Java: Page.getContent method
Python: Page.content property
.NET: Page.Content property
C: PtxPdf_Page_GetContent function

Calculating credits

To determine how many page credits you’ll need for your tasks using the Toolbox add-on, count the number of page additions and content retrievals. The key principles can be described as follows:

Each page addition to a PageList requires 1 page credit
Each call to a content getter requires 1 page credit
Copying pages without adding them to a PageList requires 0 page credits
Multiple calls to content getters on the same page require multiple page credits

For example:

Copy 5 pages: Opening a 10-page PDF, creating a new empty PDF, and copying 5 pages to it requires 5 page credits (5 page additions, no Page.Content getter calls).
Copy from multiple sources: Opening two PDFs (10 pages and 12 pages), and copying 5 pages from each PDF into a new PDF requires 10 page credits (10 page additions, no Page.Content getter calls).
Extract text from 5 pages: Opening a 10-page PDF and extracting text from 5 pages requires 5 page credits (5 Page.Content getter calls).
Create and add 5 pages: Creating a new PDF, generating 10 pages with text and images, but only adding 5 pages to the document requires 5 page credits (5 page additions, no Page.Content getter calls).
Multiple content retrievals: Opening a 1-page PDF and analyzing the text in 5 different stages, each calling the Page.Content getter, requires 5 page credits (5 Page.Content getter calls on the same page).

Best practice

Avoid repeated calls to Page.Content getters. To minimize page credit consumption, cache the page content if you need to access it multiple times.

License key validation

License keys are validated using the Pdftools Licensing Service. The Toolbox add-on 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 key number.
Toolbox add-on functions used and the number of pages processed.

Privacy

Pdftools does not receive information about documents and data processed by the Toolbox add-on. At Pdftools, we highly value our customers’ privacy.

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

Toolbox add-on validation stages

The Toolbox add-on validates the license key at different stages during operation:

Initial validation: The validity of the license key is checked when you call the initialization method:

C: Ptx_Sdk_Initialize
.NET: Sdk.Initialize
Python: Sdk.initialize
Java: Sdk.initialize

Continued validation: The license key validity is checked again when you use document operation methods:

C: PtxPdf_Document_Create, PtxPdf_Document_Open, PtxPdf_PageList_Add*, PtxPdf_Page_GetContent
.NET: Document.Create, Document.Open, Document.Add*, CopyTo*, Page.Content property
Python: Document.create, Document.open, PageList.insert, PageList.append, PageList.extend, Page.content property
Java: Document.create, Document.open, PageList.add*, Page.getContent

This includes all page list mutations and content getters described in the Licensing credit count section.

caution

Without a valid license key, these operations fail. However, these methods only test whether the license key is valid. They do not test whether the license key still provides remaining page credits.

Initialize the Toolbox add-on license

Learn how to use the Toolbox add-on license key. Review the appropriate link for your programming language:

Default license configuration

By default, when the Toolbox add-on 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 Toolbox add-on cannot connect to the licensing service URL, the SDK initialization fails.

Use the Licensing Gateway

Use the Licensing Gateway Service (LGS) if the Toolbox add-on 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
    Ptx_Initialize();

    // Set the URL to the Licensing Gateway Service.
    if (!Ptx_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 (!Ptx_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$", null);

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$", null);

from pdftools_toolbox 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$", None)

note

More information about the LicensingService property is available in the Toolbox add-on API references for C, Java, .NET, 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.
If you need to review license usage programmatically, refer to Workaround: Use Pdftools SDK to check license status.

View page credits consumption in the Pdftools Portal

Log in to the Pdftools Portal.
In the Products tab, click See product next to the Toolbox add-on.
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.

Workaround: Use the Pdftools SDK to check license status

The Toolbox add-on doesn’t provide a built-in license status check. However, the Pdftools SDK uses the same license key as the Toolbox add-on. As a workaround, you can use the Pdftools SDK to check your Toolbox add-on license usage programmatically. For more information, review Check the license status in the Pdftools SDK licensing documentation and Getting started with the Pdftools SDK.

Request a license​

Trial license​

Trial license overview​

Full license​

Find the license key​

Licensing credit count​

Page mutations​

Content getters​

Calculating credits​

License key validation​

Toolbox add-on validation stages​

Initialize the Toolbox add-on license​

Default license configuration​

Use the Licensing Gateway​

Check the license status​

View page credits consumption in the Pdftools Portal​

Workaround: Use the Pdftools SDK to check license status​