Zentitle2 Licensing API (2024-11-07:v1.0.814)

This is the documentation for the Zentitle2 Software Licensing Platform for SaaS and On-Premise applications.

Please provide feedback to your account manager on things you like and things you'd like to see.

Licensing API doesn't use OAuth2 to authenticate requests. Instead, authentication is based on tenantId, productId, and entitlement Activation Code.

The first step to use the Licensing API is to call Activate endpoint. In the response, one of the fields is accessToken. Access token should be sent with every API request in the Authorization header as:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI...

API requires one more header to be set with the ID of your Zentitle2 tenant, for example:

N-TenantId: t_KRwhRp1yl0_9gsZjE5Yjaw

API is using a nonce concept. Every request must contain a unique nonce value in the N-Nonce header. The following endpoints are not using Nonce:

• Create Activation- this is the first call in the Activation lifecycle, so there is no Nonce value yet
• Deactivate Seat - Nonce is not required to deactivate a seat. Otherwise, deactivating would be impossible in case of a lost or incorrect Nonce value.

The first Nonce is returned by the Create Activation endpoint. This Nonce must be stored by the application and used in subsequent requests, returning a new nonce for the following request. Nonce values are produced in the N-Nonce header.

It's straightforward to set up Postman to use with Zentitle2 Licensing API.

Download OpenAPI specification

You will find a Download button at the top of this page, which will download the OpenAPI specification file.

Postman import

Open Postman and click the Import button (top left). Select the downloaded file, choose "Open API 3.0 with a Postman Collection", and click the Import button.

Postman configuration

Select the imported API and the collection "Zentitle2 Licensing API" in the APIs section.

1. In the Authorization tab, select "No Auth" type.
2. In the "Pre-request Script" tab, add the following script:

pm.environment.set("baseUrl", pm.environment.get("licensingApiUrl"))
pm.request.headers.add({key: 'N-TenantId', value: pm.environment.get("tenantId") });

if (pm.request.url.path.toString() != "api,v1,activate") {
    pm.request.headers.add({key: 'N-Nonce', value: pm.environment.get("licensingApi-nonce") });
    pm.request.headers.add({key: 'Authorization', value: pm.environment.get("licensingapi-accesstoken") });
}

3. In the "Post-request Script" tab, add the following script:

var nonce = pm.response.headers.get("N-Nonce");
if (nonce) {
    pm.environment.set("licensingApi-nonce", nonce);
}

if (pm.request.url.path.toString() == "api,v1,activate") {
    var res = pm.response.json();
    pm.environment.set('licensingapi-accesstoken', res.accessToken);
}

Postman environment variables

Go to the "Environments" section on the left and create a new Environment for your Zentitle2 account:

tenantId:           {your tenant id}
licensingApiUrl:    {api url}

The script will automatically set the base URL for the API and Tenant ID header for every request.

Test the API

Select the "Create activation" request. In the Body fill in the request model and click the "Send" button. This will create a new activation for your entitlement.

In case of an error, API returns the error status code along with ApiError object if applicable.

Please see API Versioning documentation for more information about our versioning strategy and how to select API version.

2024-11-07

POST /api/v1/activate endpoint returns 201 or 200

• If the activation is created successfully, the response will contain a 201 status code.
• If existing activation is re-used, the response will contain a 200 status code.
• Previously, the response always contained a 201 status code and returned ActivationModel with less information.

POST /api/v1/activate endpoint returns richer ActivationStateModel instead of ActivationModel

• The response now contains more information including Features and Attributes. There is no need to subsequently call GET /api/v1/activation to get the data because response body will be exactly the same.

PATCH /api/v1/activation endpoint returns 402 when activation cannot be extended beyond entitlement expiry

• When activation lease expiry already equals entitlement expiry, next and any subsequent refreshes will fail with 402, since the activation cannot be extended beyond the entitlement expiry.
• Previously, the response would succeed with 200 and unchanged activation would be returned.

PATCH /api/v1/activation endpoint returns richer ActivationStateModel instead of ActivationModel

• The response now contains more information including Features and Attributes. There is no need to subsequently call GET /api/v1/activation to get the data because response body will be exactly the same.

PATCH /api/v1/activation/features/checkout now returns 200 and FeatureStateModel in the response

• This is to return enough information about the feature change by executing the Checkout action so that there is no need to perform another call to GET /api/v1/activation
• Previously, the status code was 204 and the response was empty

PATCH /api/v1/activation/features/return now returns 200 and FeatureStateModel in the response

• This is to return enough information about the feature change by executing the Return action so that there is no need to perform another call to GET /api/v1/activation
• Previously, the status code was 204 and the response was empty

PATCH /api/v1/activation/checkout REMOVED

• Use PATCH /api/v1/activation/features/checkout instead

PATCH /api/v1/activation/return REMOVED

• Use PATCH /api/v1/activation/features/return instead

2024-01-01

Initial release