Zentitle2 Licensing API (v1.0.250)

Download OpenAPI specification:Download

Overview

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.

Authentication

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

Nonce

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.

Postman Configuration

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") });

Postman environment variables

Go to the "Enrivonments" 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.

Responses

Status Meaning Description
200 OK Returned after successful GET requests. The body contains requested data
201 Created Returned after a successful POST request. The body contains created object
204 No Content Returned after successful PUT and DELETE requests. The body is empty

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

Errors

Status Meaning Description
400 Bad Request can not parse request body or parameters
401 Unauthorized missing or invalid access token
402 Request Failed parameters were valid, but the request failed
403 Forbidden insufficient permissions to perform request
404 Not Found requested resource has not been found
409 Conflict request conflicts with the current state
422 Unprocessable entity request parses correctly but fails validation
429 Too many requests too many requests hit the API too quickly
500, 502, 503, 504 Server errors something went wrong on Zentitle's end

Activate

Create activation

Activate entitlement for the provided seat id and create activation that can be used for feature management

Activation returned will be valid until the time specified in the leaseExpiry field. To continue using the seat it has to be refreshed using the refresh endpoint.

The return object contains a JWT token that can be used to authorize requests to the API.

Authorizations:
Bearer
Request Body schema: application/json
required

Properties required to create activation

productId
required
string <ProductId> non-empty

Product id for activation

activationCode
string or null <= 50 characters

Activation code DEPRECATED (will be removed): Use activationCredentials instead

(ActivationCredentialsModel (object or null))

Credentials required to activate the entitlement

One of
type
required
string (ActivationMethod)
code
required
string [ 1 .. 50 ] characters
seatId
required
string [ 1 .. 50 ] characters

Seat id

seatName
string or null <= 50 characters

Seat name (optional)

Responses

Response Schema: application/json
accessToken
string

Access Token for the LicensingAPI

id
string <ActivationId>

Activation identifier

ActivationMode (string)

Activation mode

One of
string (ActivationMode)
Enum: "online" "offline"

Activation mode

ActivationMethod (string)

Activation method

One of
string (ActivationMethod)
Enum: "activationCode" "openIdToken"

Activation method

leaseExpiry
string <date-time>

Exclusive seat lease expiry date

productId
string or null <ProductId>

Id of product licensed by entitlement

entitlementId
string or null <EntitlementId>

Id of entitlement

seatId
string

Unique id of seat provided by external system

seatName
string or null

Optional name of seat provided by external system

username
string or null

Username

activated
string <date-time>

Activation creation date

lastLease
string <date-time>

Date when activation was created/last extended

Request samples

Content type
application/json
{
  • "productId": "prod_v3oTIf5FGUaTvobxiJNhaw",
  • "activationCode": null,
  • "activationCredentials": {
    },
  • "seatId": "john.doe@elevate.com",
  • "seatName": "John Doe"
}

Response samples

Content type
application/json
{
  • "accessToken": "eyJhbGci...",
  • "id": "act_oH_hPJ3BgE0LTRYd9-k1tg",
  • "activationMode": "online",
  • "activationMethod": "activationCode",
  • "leaseExpiry": "2019-08-24T14:15:22Z",
  • "productId": "prod_oH_hPJ3BgEO187Yd9-kuTg",
  • "entitlementId": "ent_oH_hPJ3BgEO172Yd9-KuTg",
  • "seatId": "user@boeing.com",
  • "seatName": "Boeing User",
  • "username": "boeing_user",
  • "activated": "2019-08-24T14:15:22Z",
  • "lastLease": "2019-08-24T14:15:22Z"
}

Activation

Get activation state

Use this method to get current activation state from the Zentitle2 server. Return object will contain all the attributes and currently checked out features.

Authorizations:
Bearer

Responses

Response Schema: application/json
id
string <ActivationId>

Activation identifier

ActivationMode (string)

Activation mode

One of
string (ActivationMode)
Enum: "online" "offline"

Activation mode

ActivationMethod (string)

Activation method

One of
string (ActivationMethod)
Enum: "activationCode" "openIdToken"

Activation method

username
string or null

Username

leaseExpiry
string <date-time>

Exclusive seat lease expiry date

productId
string or null <ProductId>

Id of product licensed by entitlement

entitlementId
string or null <EntitlementId>

Id of entitlement

entitlementExpiryDate
string or null <date-time>

Entitlement expiry date (null if not expires)

seatId
string

Unique id of seat provided by external system

seatName
string or null

Optional name of seat provided by external system

activated
string <date-time>

Activation creation date

lastLease
string <date-time>

Date when activation was created/last extended

Array of objects (AttributeStateModel)

Array of activation attributes

Array
key
string

Attribute key

AttributeType (string)

Attribute type

value
string or null

Attribute value

Array of objects (FeatureStateModel)

Array of activation features

Array
key
string

Feature key

FeatureType (string)

Feature type

active
integer or null <int64>

Amount of feature being currently checked out by activation

available
integer or null <int64>

Amount of feature that is still available for checkout (amount form active filed is excluded)

total
integer or null <int64>

Total amount of feature in entitlement

entitlementGracePeriodExpiry
string or null <date-time>

Entitlement grace period expiry date (null if not used)

(EntitlementStatus (string or null))

Entitlement status

One of
string or null (EntitlementStatus)
Enum: "active" "gracePeriod" "expired" "disabled" "exported" "created" "customerDisabled"

Entitlement status

Response samples

Content type
application/json
{
  • "id": "act_oH_hPJ3BgE0LTRYd9-k1tg",
  • "mode": "online",
  • "activationMethod": "activationCode",
  • "username": "boeing_user",
  • "leaseExpiry": "2019-08-24T14:15:22Z",
  • "productId": "prod_oH_hPJ3BgEO187Yd9-kuTg",
  • "entitlementId": "ent_oH_hPJ3BgEO172Yd9-KuTg",
  • "entitlementExpiryDate": "2019-08-24T14:15:22Z",
  • "seatId": "user@boeing.com",
  • "seatName": "Boeing User",
  • "activated": "2019-08-24T14:15:22Z",
  • "lastLease": "2019-08-24T14:15:22Z",
  • "attributes": [
    ],
  • "features": [
    ],
  • "entitlementGracePeriodExpiry": "2019-08-24T14:15:22Z",
  • "entitlementStatus": "active"
}

Refresh seat activation

Refresh the seat to extend the activation lease time

Authorizations:
Bearer

Responses

Response Schema: application/json
accessToken
string

Access Token for the LicensingAPI

id
string <ActivationId>

Activation identifier

ActivationMode (string)

Activation mode

One of
string (ActivationMode)
Enum: "online" "offline"

Activation mode

ActivationMethod (string)

Activation method

One of
string (ActivationMethod)
Enum: "activationCode" "openIdToken"

Activation method

leaseExpiry
string <date-time>

Exclusive seat lease expiry date

productId
string or null <ProductId>

Id of product licensed by entitlement

entitlementId
string or null <EntitlementId>

Id of entitlement

seatId
string

Unique id of seat provided by external system

seatName
string or null

Optional name of seat provided by external system

username
string or null

Username

activated
string <date-time>

Activation creation date

lastLease
string <date-time>

Date when activation was created/last extended

Response samples

Content type
application/json
{
  • "accessToken": "eyJhbGci...",
  • "id": "act_oH_hPJ3BgE0LTRYd9-k1tg",
  • "activationMode": "online",
  • "activationMethod": "activationCode",
  • "leaseExpiry": "2019-08-24T14:15:22Z",
  • "productId": "prod_oH_hPJ3BgEO187Yd9-kuTg",
  • "entitlementId": "ent_oH_hPJ3BgEO172Yd9-KuTg",
  • "seatId": "user@boeing.com",
  • "seatName": "Boeing User",
  • "username": "boeing_user",
  • "activated": "2019-08-24T14:15:22Z",
  • "lastLease": "2019-08-24T14:15:22Z"
}

Deactivate seat

Deactivate the seat and return all checked out features

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "details": "string",
  • "error": "string",
  • "errorCode": "string",
  • "validationErrors": [
    ]
}

Get entitlement metadata associated with the current activation

Authorizations:
Bearer

Responses

Response Schema: application/json
customerName
string or null

Customer name

customerAccountRefId
string or null

Customer account reference id

orderRefId
string or null

Order reference number

offeringName
string

Offering name

sku
string

Unique offering identifier

productName
string

Product name

PlanModel (object)

Plan details

One of
name
string

Plan name

LicenseType (string)

License type

One of
string (LicenseType)
Enum: "subscription" "perpetual"

License type

LicenseStartType (string)

License start

One of
string (LicenseStartType)
Enum: "activation" "entitlementCreation" "custom" "manualActivation"

License start

Interval (object)

License duration

One of
type
required
string (IntervalType)
Enum: "none" "day" "week" "month" "year" "hour" "minute"
count
integer or null [ 1 .. 32767 ]
Interval (object)

Grace period

One of
type
required
string (IntervalType)
Enum: "none" "day" "week" "month" "year" "hour" "minute"
count
integer or null [ 1 .. 32767 ]
Interval (object)

Linger period

One of
type
required
string (IntervalType)
Enum: "none" "day" "week" "month" "year" "hour" "minute"
count
integer or null [ 1 .. 32767 ]
Interval (object)

Lease period

One of
type
required
string (IntervalType)
Enum: "none" "day" "week" "month" "year" "hour" "minute"
count
integer or null [ 1 .. 32767 ]
Interval (object)

Offline lease period

One of
type
required
string (IntervalType)
Enum: "none" "day" "week" "month" "year" "hour" "minute"
count
integer or null [ 1 .. 32767 ]

Response samples

Content type
application/json
{
  • "customerName": "Boeing Corporation",
  • "customerAccountRefId": "account12395-32",
  • "orderRefId": "order476-2547",
  • "offeringName": "Elevate Standard 1year subscription 1seat",
  • "sku": 1000,
  • "productName": "Elevate",
  • "plan": {
    },
  • "gracePeriod": {
    },
  • "lingerPeriod": {
    },
  • "leasePeriod": {
    },
  • "offlineLeasePeriod": {
    }
}

ActivationFeatures

Checkout feature

This method checkouts feature. Feature can be used permanently (consumption token) or can be returned (element pool, floating) using return feature method.

Authorizations:
Bearer
Request Body schema: application/json
required

Properties required to checkout feature

key
required
string [ 1 .. 50 ] characters

Feature key

amount
required
integer <int64> [ 1 .. 9223372036854780000 ]

Amount to checkout

Responses

Request samples

Content type
application/json
{
  • "key": "Workers",
  • "amount": 1
}

Response samples

Content type
application/json
{
  • "details": "string",
  • "error": "string",
  • "errorCode": "string",
  • "validationErrors": [
    ]
}

Return feature

This method returns feature. Only features of following types (element pool, floating) are allowed to be returned

Authorizations:
Bearer
Request Body schema: application/json
required

Properties required to return feature

key
required
string [ 1 .. 50 ] characters

Feature key

amount
required
integer <int64> [ 1 .. 9223372036854780000 ]

Amount of feature to return

Responses

Request samples

Content type
application/json
{
  • "key": "Workers",
  • "amount": 1
}

Response samples

Content type
application/json
{
  • "details": "string",
  • "error": "string",
  • "errorCode": "string",
  • "validationErrors": [
    ]
}