Licensing & Management APIs
On-premise apps
NET applications
If you want to implement Zentitle2 in an on-premise app, you can use: - .NET SDK - if .NET is your platform, then the best way is to use our .NET SDK Nuget package. We have prepared it so that it's easy to integrate and provides an API into Zentitle2 functionality. Please refer to the documentation and sample applications we provide to see how to implement the most common scenarios.
Other platforms
On other platforms - you can use our Licensing API to activate seats and manage features securely.
The Licensing API doesn't require you to store any secrets in the application. It uses a Product ID and Activation Code to activate your entitlements.
Using open-source tools, you can use the OpenAPI specification we provide to generate a Client SDK for the most popular platforms.
SaaS applications and back-office integration
The best choice for Backoffice integrations or SaaS applications is our Management API.
It uses the OAuth2 protocol for authentication and allows you to set up and use all features of Zentitle, like creating entitlement, provisioning it, and activating seats.
You can also subscribe to system events via webhooks.
This allows you to react to various events, like entitlement created, entitlement provisioning, notifications about entitlement expiration (30, 7 days before), etc.
Credentials for Management API & Webhooks can be managed from the Zentitle2 UI.
Zentitle2 has two APIs: a licensing API and a management API.
Object IDs
Most objects within Zentitle2 have an ID that can be used with the Management API to reference that object.
IDs follow the convention of having a standard prefix for that object type (e.g. cust_, prod_, etc.) followed by a 22-character alphanumeric string.
The entire ID should be provided to the relevant Management API call.
Using APIs
The credentials from these APIs are an essential part of the setup and testing phases, and they form part of the key data required to "wire up" your apps to Zentitle2.
Once you have the credentials, start using the APIs
This is the specific API documentation for the Zentitle2 for SaaS and On-Premise applications.
Management API - The REST API to:
Manage entitlements within the Zentitle2 platform.
Activate, query, and manage entitlements from SaaS applications.
Licensing API - How to activate, query, and manage entitlements from On-Premise applications.
API docs
You can find our API docs here:
This is the specific API documentation for the Zentitle2 for SaaS and On-Premise applications.
Management API - The REST API to:
Manage entitlements within the Zentitle2 platform.
Activate, query, and manage entitlements from SaaS applications.
Licensing API - How to activate, query, and manage entitlements from On-Premise applications.
API Rate limits
The Zentitle2 APIs use a number of safeguards against bursts of incoming traffic to help maximize its stability.
These types of circumstances may result in rate limiting:
Users who send many requests in quick succession might see error responses.
Running a large volume of closely spaced requests.
Issuing many long-lived requests.
A sudden increase in transaction volume.
Any activity that appears to our systems is like a DDOS attack.
We have several limiters in the API, including:
A rate limiter that limits the number of requests received by the API within any given second.
A concurrency limiter that limits the number of requests that are active at any given time. Problems with this limiter are less common than the request rate limiter, but it’s more likely to result in resource-intensive, long-lived requests.
If you suddenly see a rising number of rate-limited requests, please get in touch with support.
We may reduce limits to prevent abuse or increase limits to enable high-traffic applications. To request an increased rate limit, please get in touch with support. If you’re requesting a large increase, contact us six weeks before you’ll need the increased rate limit.
Collecting credentials for integration
Details you need to embed from the customer portal
In order to use the code with each of your "products," you will need to wire up the app, the client, and the APIs using data collected from the dashboard provided with Zentitle2.
On-premise and SDK-based applications
On-premise and SDK-based implementations use the Licensing API. The Licensing API doesn't use OAuth2 to authenticate requests. Instead, authentication is based on tenantId, productId, and entitlement Activation Code.
Then, you need "activation codes" for testing based on the product entitlements you will create.
Note there are two options on the API Credentials page, so ensure you pick the correct API details.
The details you will need to collect for your implementation are:
Tenant Id (API) - for authentication
zentitleApiUrl - API URL
Product Id - for identifying which product to license
Activation codes - to test (per the rights in the entitlement)
Tenant Id and API URL
Found under the Licensing API Details section, the TenantId, OAuth URL, and API URLs can be easily copied using the "copy" button on the left.
The parameters are located under the "Administration" > "API Credentials" on the top menu.
Example in code: .WithTenant("t_KRwhRp1yl0_9gsZjE5Yjqq") for SDK
Product Id
The Product Id is located under the "Product Catalog" > "Products" > "YourProduct" on the left menu.
First, click on the "Products" link in the left menu,
Then, choose the product you have added you wish to integrate.
Click the product name.
The Product ID can be easily copied using the "copy" button on the left.
Example in code: .WithProduct("prod_GROAP541F0qw2XzDQSOyrg")
Activation codes
The Activation codes are located under the "Entitlements" > "Activation codes" on the left menu.
First, click the entitlement you will be testing.
Then, navigate to the activation codes tab on the entitlement page and find the activation codes in the "Activation Codes" section.
Test codes can be easily copied using the "copy" button on the left.
Testing
In the API docs, we also show how to setup Postman so you can test the API:
https://api.nalpeiron.io/docs/#section/Postman-Configuration
Integrating with the SDK
Now you should have all the data required to set up the SDK and test it.
SaaS and API-based implementations
Collecting the serverside parameters to input into the config file
Zentitle2 Management API uses OAuth2 over HTTPS to manage authentication and authorization.
https://api.nalpeiron.io/docs/#section/Authentication
You will also need "activation codes" for testing based on the product entitlements you will create.
The details you will need to collect for your implementation are:
Tenant Id (API) - for authentication
oauth_url - OAuth URL
zentitleApiUrl - API URL
ProductID - unique code for the product being tested
Generate these:
client Id - your ID
clientSecret - secret key
Activation codes - to test (per the rights in the entitlement)
Most of these are in the interface, but you must generate the API client and secret in API Credentials.
Tenant Id, OAuth URL, and API URLs
The TenantId is located under the "Administration" > "API Credentials" on the left menu.
Found under the Management API Details section, the TenantId, OAuth URL, and API URLs can be easily copied using the "copy" button on the left.
API requires one more header to be set with Id of your Zentitle2 tenant, for example:
Client Id and clientSecret
The client ID and client secret need to be generated in the same section by clicking the "add API client" button in the right-hand part of the "Management API Clients" section.
Next, name the ClientID and save the name for the integration process.
Click save.
You can view the key by clicking the "eye" icon or copying it.
The "copy" button on the right can easily copy the secret key.
e.g. Twfx2Q5mH0izUXshrsTe3z3PIwkje22y
Before closing, copy and save the Client Secret for the integration process.
Download Postman file
Once you have saved the API client, you can also download a package containing all the data you need for Postman.
Activation codes
The Activation codes are located under the "Entitlements" > "Activation codes" tab on the left menu.
This example assumes you have already created entitlements and added activation codes.
First, click the entitlement you will be testing from the list.
Then, navigate to the activation codes tab on the entitlement page and find the activation codes in the "Activation Codes" section.
Test codes can be easily copied using the "copy" button on the left.
ProductID
Getting your product id code is easy.
Simply log in and go to the products page.
Find the test product, click on the product name, and review the "details" tab.
Copy the ID line.
Paste that data into the correct line in the config app.
Testing
In the API docs we also show how to setup Postman so you can test the API:
https://api.nalpeiron.io/docs/#section/Postman-Configuration
Integrating with the API
You should have all the data required to integrate and test your app.
API Versioning
Versioning Strategy
Our APIs utilize date-based versioning to identify the version with the specific date on which they were released. Our initial API version for both the Licensing and Management APIs is 2024-01-01. However, both of these APIs are being versioned independently. The new version is introduced when a backward-incompatible change is made to the API.
We consider the following changes to be backward-compatible:
Adding new API resources and API methods
Adding new optional request parameters to the existing API methods
Adding new properties to the existing API responses
Changing the order of properties in the existing API responses
Selecting the API version
When making an HTTP request to the API, the API version can be specified via the 'N-Api-Version' header or the 'n-api-version' query parameter. If the API version is not specified in the HTTP request, the default API version is used instead. Inspect the 'N-Api-Version' response header to verify which version of the API has been used when processing the API request.
Default API Version
The initial API call made from your account sets the default API version to the latest stable version available at that moment. To see and edit the default API versions for both the Management and the Licensing API, visit the API Credentials page.