Create a tenant
Create a tenant
Qlik Cloud enables partners to integrate the tenant provisioning process directly into their onboarding flows with a tenant creation API endpoint. In this tutorial, you are going to create a tenant programmatically.
Tenant provisioning is handled by My Qlik, the subscription management portal for Qlik Cloud.
If you haven't used these features before, please reach out to your Qlik account manager as it's likely that you will need changes made to your Qlik entitlement before you begin.
Sections
- Code examples
- Prerequisites
- Variable substitution and vocabulary
- 1. Generate credentials
- 2. Obtain the signed entitlement key
- 3. Obtain an access token for creating tenants
- 4. Create a tenant
- 5. Request an access token for the tenant
- 6. Send an API request to the tenant
- Next steps
Code examples
Complete script examples for creating a tenant using qlik-cli, curl, Python, and API collections are available here.
Prerequisites
- An active entitlement with multiple tenants allocated (you can confirm this with your Qlik sales contact).
- You have created an initial tenant; either by following the instructions in
your Qlik welcome email, or by logging into My Qlik
directly and clicking
Create tenant
on the relevant entitlement. - Development environment or terminal for running examples on the command-line.
- cURL for running the inline examples.
Note: The initial tenant that you created interactively will be referred to as the
<SOURCE_TENANT>
. You can use the source tenant to create Qlik Sense applications, data sets, and other assets (referred to ascontent
) for deployment to one or multiple end customer tenants referred to as<TARGET_TENANT>
through this tutorial series.
Variable substitution and vocabulary
Throughout this tutorial, variables will be used to communicate value placement.
The variable substitution format is <VARIABLE_NAME>
. Here is a list of variables
referred to in this tutorial.
Variable | Description |
---|---|
<SOURCE_TENANT> | The domain for the initial tenant created during account onboarding. Equivalent to tenanthostname.<REGION>.qlikcloud.com . |
<TARGET_TENANT> | The domain for the new tenant that this tutorial will create. Equivalent to tenanthostname.<REGION>.qlikcloud.com . |
<TENANT_REGISTRATION> | The registration endpoint used for requesting new Qlik Cloud tenants. Equivalent to register.<REGION>.qlikcloud.com |
<REGION> | The region identifier for the Qlik Cloud region that you're sending requests to. Examples include ap for Australia, eu for Ireland, sg for Singapore and us for North America. |
<CLIENT_ID> | The client ID for an OAuth client, specific to the region you're sending requests to. |
<CLIENT_SECRET> | The client secret for the specific OAuth <CLIENT_ID> . |
<SOURCE_ACCESS_TOKEN> | A bearer token for authorizing https requests to the <SOURCE_TENANT> . |
<TARGET_ACCESS_TOKEN> | A bearer token for authorizing https requests to the <TARGET_TENANT> . |
<REGISTER_ACCESS_TOKEN> | A bearer token for authorizing https requests to the <TENANT_REGISTRATION> endpoint. |
<SIGNED_ENTITLEMENT_KEY> | The signed key required to create tenants, linked to your entitlement or subscription. |
1 Generate credentials
Creating tenants requires generating an OAuth client for each region where you plan to have tenants reside. Generate OAuth clients by selecting the subscription in My Qlik with the multiple tenants entitlement.
Note: OAuth clients and their associated credentials do not expire. Once created, you can regenerate the secret for the OAuth client, or delete the client altogether. Each time you create an OAuth client, a new
bot user
is created on accessed tenants. These users are not automatically removed when an OAuth client is deleted, so keep this in mind for your tenant management processes.
Sign into My Qlik
Sign in to My Qlik and identify the subscription with the multiple tenants entitlement added to it.
Manage OAuth clients
Click the ellipsis (...
) on the right side of the subscription entry and select
Manage OAuth clients.

Select the region the OAuth credential is going to support. The system returns a client ID and client secret.

Client IDs and corresponding
secrets are unique to the region and can't generate access tokens in
different regions. Record the <CLIENT_ID>
and the <CLIENT_SECRET>
and keep them
safe and secure because the <CLIENT_SECRET>
is not visible after generation.
Note: This tutorial assumes that you wish to create your new
<TARGET_TENANT>
in the same Qlik Cloud region as your existing<SOURCE_TENANT>
. If these regions are different, you should modify the examples below to pass in the correct OAuth client (<CLIENT_ID>
and<CLIENT_SECRET>
) and region for each command.
2 Obtain the signed entitlement key
The <SIGNED_ENTITLEMENT_KEY>
is needed to create additional tenants. To obtain the
<SIGNED_ENTITLEMENT_KEY>
, you are going to request an access token from the
<SOURCE_TENANT>
, and use that access token to request the <SIGNED_ENTITLEMENT_KEY>
.
Request an access token
Note: Access tokens are scoped to individual tenants - this means that you need to retrieve an access token via the
/oauth/token
endpoint for each tenant. An access token that's generated for a given tenant can be used an unlimited number of times, however, the token expires six hours after its issued. If your scripts run longer than six hours you'll need to retrieve a new access token during script execution.
Request an access token from the <SOURCE_TENANT>
using the <CLIENT_ID>
and
<CLIENT_SECRET>
, and OAuth client_credentials
grant type in a JSON object:
{
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"grant_type": "client_credentials"
}
Send a request to the OAuth token endpoint on the <SOURCE_TENANT>
:
curl -L "https://<SOURCE_TENANT>/oauth/token" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"client_id":"<CLIENT_ID>", "client_secret":"<CLIENT_SECRET>", "grant_type":"client_credentials"}'
The result is a JSON object displaying the <SOURCE_ACCESS_TOKEN>
for the
built-in user that represents the OAuth client that you used to make the
request. This built-in user is known as a bot user
.
{
"access_token": "<SOURCE_ACCESS_TOKEN>",
"token_type": "bearer",
"expires_at": "2022-06-03T20:52:08.000Z",
"expires_in": 21600
}
Retrieve the signed entitlement key
To obtain the signed entitlement key, make a request to the licenses/overview
endpoint with the <SOURCE_ACCESS_TOKEN>
:
curl -L "https://<SOURCE_TENANT>/api/v1/licenses/overview" \
-H "Authorization: Bearer <SOURCE_ACCESS_TOKEN>" \
-H "Accept: application/json" \
-H "Content-Type: application/json"
The result is a JSON object containing the signed entitlement key:
{
"licenseNumber": "012345678912345678",
"licenseKey": "<SIGNED_ENTITLEMENT_KEY>",
"valid": "./2023-05-30",
"status": "Ok",
"origin": "Internal",
"updated": "0001-01-01T00:00:00Z",
"trial": false,
"allotments": [
{
"name": "professional",
"usageClass": "assigned",
"units": 25,
"unitsUsed": 1,
"overage": 0
},
]...
}
Record the licenseKey
value as the <SIGNED_ENTITLEMENT_KEY>
and
store it someplace safe for future use.
3 Obtain an access token for creating tenants
Creating tenants requires an access token from a publicly available
<TENANT_REGISTRATION>
endpoint in each Qlik Cloud region. Once you obtain an
access token from the <TENANT_REGISTRATION>
endpoint, you can contact the
endpoint to create new tenants.
To obtain an access token for creating tenants, issue a REST request to the
<TENANT_REGISTRATION>
from the same region that you created the OAuth client ID
and secret in.
{
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"grant_type": "client_credentials"
}
Using cURL, send the request:
curl -L "https://<TENANT_REGISTRATION>/oauth/token" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"client_id":"<CLIENT_ID>", "client_secret":"<CLIENT_SECRET>", "grant_type":"client_credentials"}'
The result is a JSON object with an access token that you will use to create a tenant:
{
"access_token": "<REGISTER_ACCESS_TOKEN>",
"token_type": "bearer",
"expires_at": "2022-06-03T18:29:45.000Z",
"expires_in": 21600
}
With the <SIGNED_ENTITLEMENT_KEY>
and <REGISTER_ACCESS_TOKEN>
in hand, you're
ready to create a tenant programmatically.
4 Create a tenant
Create a tenant by issuing a request to the tenant registration endpoint
(https://<TENANT_REGISTRATION>/api/v1/tenants
). Include the <REGISTER_ACCESS_TOKEN>
in the Authorization
header and the <SIGNED_ENTITLEMENT_KEY>
as a JSON object in the request body.
Using cURL, send the request:
curl -L "https://<TENANT_REGISTRATION>/api/v1/tenants" \
-X POST \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"licenseKey":"<SIGNED_ENTITLEMENT_KEY>"}'
The result is a JSON object with the new tenant hostname:
{
"id": "TZXk9rFMoKgp7sgAwvczdAlKSSWuaa3e",
"name": "ire7t7hg58avbmx",
"hostnames": ["<TARGET_TENANT>"],
"createdByUser": "",
"datacenter": "us-east-1",
"created": "2022-06-02T13:51:58.503Z",
"lastUpdated": "2022-06-02T13:51:58.503Z",
"status": "active",
"autoAssignCreateSharedSpacesRoleToProfessionals": true,
"enableAnalyticCreation": false,
"links": {
"self": {
"href": "https://<TENANT_REGISTRATION>/api/v1/tenants/TZXk9rFMoKgp7sgAwvczdAlKSSWuaa3e"
}
}
}
Record the first value of the hostnames
array (there should be only one value)
as the <TARGET_TENANT>
value for later use.
5 Request an access token for the tenant
Now that the target tenant has been created, you need to obtain an access token from the tenant to make REST requests using the client ID, client secret, and OAuth credential grant type in a JSON object.
{
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"grant_type": "client_credentials"
}
Send a request to the OAuth token endpoint on the new tenant:
curl -L "https://<TARGET_TENANT>/oauth/token" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"client_id":"<CLIENT_ID>", "client_secret":"<CLIENT_SECRET>", "grant_type":"client_credentials"}'
The result is a JSON object containing the <TARGET_ACCESS_TOKEN>
.
{
"access_token": "<TARGET_ACCESS_TOKEN>",
"token_type": "bearer",
"expires_at": "2022-06-03T20:52:08.000Z",
"expires_in": 21600
}
6 Send an API request to the tenant
The tenant access token authorizes the API requests you make to the tenant you created. Test the connectivity and access to the new tenant by making a request to the users endpoint.
Using cURL, send the request to the
https://<TARGET_TENANT>/api/v1/users/me
endpoint with the tenant
access token in the Authorization
header:
curl -L "https://<TARGET_TENANT>/api/v1/users/me" \
-H "Authorization: Bearer <TARGET_ACCESS_TOKEN>" \
-H "Accept: application/json" \
-H "Content-Type: application/json"
The result is a JSON object displaying the metadata for the built-in bot
user.
{
"id": "629a20185b4a5194788d9c1e",
"tenantId": "7WZ_qyWDvlS8AvNkye9y20dn-miC0URf",
"clientId": "<CLIENT_ID>",
"status": "active",
"subject": "qlikbot\\00cbb22c600e823ed278d5e3d976f85b",
"name": "US OAuth Client",
"roles": ["TenantAdmin"],
"assignedRoles": [...],
"assignedGroups": [],
"groups": [],
"createdAt": "2022-06-03T14:52:08.925Z",
"lastUpdatedAt": "2022-06-03T14:52:08.925Z",
"created": "2022-06-03T14:52:08.925Z",
"lastUpdated": "2022-06-03T14:52:08.925Z",
"links": {...}
}
Next steps
If you want to validate that the tenant you created is operational, you can add an interactive user to the tenant and log in through a browser. Otherwise, you are ready to configure the tenant for use.