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.

Note: A region level OAuth client is required to create new tenants.

Code examples

Complete script examples for creating a tenant using qlik-cli, curl, Python, and API collections are available here.

Prerequisites

An OAuth client and existing source tenant
Development environment or terminal for running examples on the command-line.
cURL for running the inline examples.

Notes:

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 as content) for deployment to one or multiple end customer tenants referred to as <TARGET_TENANT> through this tutorial series.

The cURL examples in this tutorial show the command syntax for Windows Command Prompt. If you are using another command line interface, different syntax may be required for line continuation. You may also need to adjust the number and type of quotes surrounding the parameters and their values.

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 or tenant 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

Locate the <CLIENT_ID> and <CLIENT_SECRET> for the Qlik Cloud region you wish to create the new tenant in. Review how to generate OAuth credentials if you need new clients.

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 your browser. Otherwise, you are ready to configure the tenant for use.