Zentitle2 Management API (2024-01-01:v1.0.663)

This is the documentation for 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.

Zentitle2 Management API uses OAuth2 over https to manage authentication and authorization.

OAuth2 is an open standard for authorization that enables applications to securely access resources from other apps or services. We use client_credentials flow in the API.

In the client credentials flow, the app sends a request to the authorization server's token endpoint with its client ID and secret, which are used to authenticate the app. If the request is successful, the authorization server returns an access token, which the app can use to access protected resources on the resource server.

The client credentials flow is typically used by server-side apps or apps that run in a trusted environment, such as a secure server or device. It allows these apps to access protected resources on behalf of themselves, rather than on behalf of a user. This grant type is not suitable for browser-based apps or mobile apps, as it does not involve user interaction and does not provide a way for users to grant access to their protected resources.

Here is an example of how to generate client credentials for OAuth2:

1. Register your application in the Zentitle2 administration site in the "API Credentials" section.

2. During the registration process, the authorization server will provide you with a client secret for your provided client ID. These are unique, secret values that identify your app and are used to authenticate your requests to the authorization server.

3. In order to use the client credentials grant type, your app must be able to securely store the client ID and secret. These values should never be shared or exposed to anyone outside of your app, as they provide access to the authorization server on your app's behalf.

4. Once you have securely stored the client ID and secret, you can begin making requests to the authorization server's token endpoint using the client credentials grant type. This typically involves sending a POST request to the token endpoint, with the client ID and secret provided in the request body.

5. You will find the token endpoint URL in the Zentitle2 administration site in the "API Credentials" section. Please be aware that the token endpoint URL provided in the UI is the main URL to the IDP for your account. To make a request to the token endpoint, you will need to append /protocol/openid-connect/token to the URL.

6. If the request is successful, the authorization server will return an access token, which can be used to access protected resources on the resource server. The access token may also include a refresh token, which can be used to obtain a new access token when the original one expires.

Here is an example code in JavaScript that gets the access token:

var body = 'grant_type=client_credentials'
            + '&client_id=' + clientId
            + '&client_secret=' + clientSecret;
pm.sendRequest({
    url: oauth_url + '/protocol/openid-connect/token',
    method: 'POST',
    header: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Accept': 'application/json'
    },
    body: {
        mode: 'raw',
        raw: body
    }
}, function (err, res) {
    var response = res.json();
    environment.set("access_token", response.access_token);
    environment.set("token_time", Date.now() + response.expires_in * 1000);
});

Access token should be sent with every API request in the Authorization header as:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI...

Whenever the Authorization section for an endpoint contains more than one role in the list, it means that any of those roles is sufficient to access this endpoint.

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

N-TenantId: t_KRwhRp1yl0_9gsZjE5Yjaw

The Zentitle2 API adheres to the ISO 8601 standard for date and time formatting. For instance, "2021-12-31T23:59:59Z" signifies the final second of the year 2021 in the UTC time zone. The backend systems of Zentitle2 function in UTC, and as such, all DateTime fields returned by the API are also in UTC. To enhance the usability of our API, we accept datetime values in several formats:

• 2021-12-31T23:59:59Z - UTC time
• 2021-12-31T23:59:59 - dates without timezone information are assumed to be UTC time
• 2021-12-31T23:59:59+01:00 - time with timezone information

It's very easy to setup Postman to use with Zentitle2 Management API.

1. Download OpenAPI specification (top of this page)
2. Import downloaded file to Postman
3. Select "No Auth" in the Auth tab (auth will be done using pre-request script).
4. Add following script in the pre-request script tab:

pm.environment.set("baseUrl", pm.environment.get("zentitleApiUrl"));

var setAuthHeaders = () => {
    pm.request.headers.add({key: 'N-TenantId', value: pm.environment.get("tenantId") });
    pm.request.headers.add({key: 'Authorization', value: pm.environment.get("oauth_token") });
};

if (pm.environment.get("token_time") && pm.environment.get("token_time") > Date.now()) {
    setAuthHeaders();
    return;
}

var body = 'grant_type=client_credentials'
    + '&client_id=' + pm.environment.get("clientId")
    + '&client_secret=' + pm.environment.get("clientSecret");
pm.sendRequest({
    url: pm.environment.get("oauth_url"),
    method: 'POST',
    header: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Accept': 'application/json'
    },
    body: {
        mode: 'raw',
        raw: body
    }
}, function (err, res) {
    var response = res.json();
    pm.environment.set("oauth_token", 'Bearer ' + response.access_token);
    pm.environment.set("token_time", Date.now() + response.expires_in * 1000);

    setAuthHeaders();
});

5. Set up a new Postman Environment using the JSON configuration file downloaded from Zentitle2.

   • Start by launching Zentitle 2 and navigating to the 'Account > API Credentials' section.
   • Locate the 'Management API Clients' box and click on the 'Add API Client' button.
   • Provide a unique Client ID and remember to save it.
   • To download your configuration file, click on the 'Download Postman environment configuration' button.
   • Once you have your configuration file, open the Postman application.
   • In the left sidebar of the Postman application, click on the 'Environments' tab.
   • Inside the Environments tab, find and click on the 'Import' button.
   • A dialog box will appear. Click on 'files' and navigate to the location where your JSON file is stored.
   • Select the JSON file that contains the Postman environment variables and click on 'Open'.
   • Postman will import the environment variables from the JSON file. These variables will be visible in the 'Environments' section in the sidebar.
   • To use the imported environment, select it from the environment dropdown. This dropdown is located in the top right corner of the Postman application.

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