Qlik servers

Connects KPImailer to your Qlik Sense deployment - one on-premise Qlik Sense Enterprise server and one Qlik Cloud tenant - and controls how hard each connection is worked.

Permissions

Found in Settings → Qlik servers, an administrator-only area. Adding your first server of each kind is covered in first-run setup - this page covers editing an existing connection, credential rotation, and the tuning options.

Setting up Qlik Cloud access

Before you can connect a Qlik Cloud tenant, either here or in the first-run wizard, an administrator of that tenant needs to create an OAuth2 machine-to-machine (M2M) client and a Web integration in the tenant’s own Management Console. This happens entirely on the Qlik Cloud side, not in KPImailer.

Create the OAuth client (M2M)

1. In Qlik Cloud, open the Administration activity center and go to Integrations → OAuth.
2. Select Create new. Give it a name that identifies the integration (for example KPImailer) and set Client type to Web - Qlik Cloud doesn’t have a separate “machine-to-machine” client type; M2M is a mode within the Web type.
3. Turn on Machine-to-machine. Leave M2M user impersonation off - KPImailer authenticates as its own dedicated identity, not as an impersonated user.
4. Under Authentication method, leave Client secret selected so Qlik Cloud generates one for you.
5. Choose the scopes to grant - see Minimum privileges for the bot user below before accepting Qlik Cloud’s defaults.
6. Select Create. The Client ID and Client secret are both shown once - copy them straight into KPImailer’s Qlik Cloud connection form, since Qlik Cloud won’t display the secret again after this screen closes.
7. Open the new client’s ⋮ menu and select Change consent method → Trusted. This step is easy to miss but required - an M2M client left on its default consent method can’t authenticate without a user present, which is exactly how KPImailer uses it.

Create a Web integration

Separately from the OAuth client, KPImailer also needs a Web integration ID. This isn’t part of authentication - it’s a CORS allowlist that tells Qlik Cloud which origins are allowed to load Qlik content in a browser, which KPImailer needs when rendering Qlik sheets and objects into reports.

1. In the same Administration activity center, go to Integrations → Web.
2. Select Create new, give it a name, and add the exact origin KPImailer is reachable at - for example https://your-kpimailer-server (include the port if it isn’t 443). Qlik Cloud doesn’t support wildcards, so this must match exactly.
3. Select Add, then Create. Copy the resulting Web integration ID into KPImailer alongside the OAuth client ID and secret.

Minimum privileges for the bot user

The first time the OAuth client requests a token, Qlik Cloud automatically creates a hidden bot user for it - this is the identity KPImailer actually acts as against your tenant.

Caution

By default, Qlik Cloud assigns that bot user the Tenant Admin role - full administrative control over the entire tenant, including every user’s personal space. This is Qlik Cloud’s own default for every M2M OAuth client, not something KPImailer requests - right-size it immediately after connecting rather than leaving it as-is.

To reduce it: go to Administration activity center → Manage users → All users, find the bot user (named after the OAuth client you created), open Manage roles, and replace Tenant Admin with:

• Analytics Admin - a built-in role that can read and manage every app across every shared and managed space tenant-wide, which is what KPImailer needs to populate the Qlik Repository and support “All apps” alerts, without also granting user administration or access to other people’s personal spaces.
• A custom role granting the Use webhooks permission, so KPImailer can create the webhook subscription described under Test connection below.

At minimum, select these scopes on the OAuth client itself (step 5 above): admin.apps:read, admin.spaces:read, apps.report:export, and webhooks - scopes only narrow what the token can do, they never grant more than the bot user’s role already allows. If KPImailer reports a permission error for a specific action after tightening access, that error names the missing piece - add it rather than reverting to Tenant Admin.

Note

A tenant-wide webhook - one that sees reload events for every app, not just ones the bot user owns directly - currently requires the bot user to hold Tenant Admin in Qlik Cloud; Analytics Admin isn’t enough for that specific piece. If full reload-alert coverage across every app matters more to you than trimming this one privilege, it’s reasonable to leave the bot user on Tenant Admin - that’s the trade-off Qlik Cloud’s own default makes for you. Either way, a role change takes effect on the bot user’s next token request, not retroactively - re-run Test connection afterwards to confirm it still authenticates.

Tip

Qlik Cloud automatically gives the bot user a license seat the first time it performs an action that needs one - a Professional seat on user-based subscriptions, or a seat matching its assigned role on capacity-based subscriptions. This is normal and not something you configure, but it’s worth knowing before you’re surprised by a seat count change.

Steps

1. Open Settings → Qlik servers. Each configured server shows a Configured badge, its display name and URL, and when apps were last synced.

2. Select Edit on a server to change its settings.

   On-premise (certificate-authenticated Qlik Sense Enterprise on Windows):

   

   • Display name, Server URL (the Qlik Sense proxy base URL, including https://), User directory, and Service account user identify the connection.
   • Max parallel executions caps concurrent extractions against this server - 4 is a safe default.
   • Client certificate - upload a .pfx or .p12 client certificate to authenticate. Certificate password is encrypted and not shown again; leave it blank to keep the current one.

   Qlik Cloud (OAuth2 machine-to-machine client):

   

   • Display name and Tenant URL (including https://) identify the tenant.
   • OAuth client ID, Web integration ID, and OAuth client secret come from the OAuth client and Web integration you create in the Qlik Cloud tenant - see Setting up Qlik Cloud access above for exact steps. OAuth client secret is encrypted and never shown again after saving - leave it blank to keep the current one.

3. Select Test connection before saving. The checks shown differ by server type: on-premise verifies Server reachable, Authentication, User exists, RootAdmin, and Virtual proxy ready - on-premise only, this step also automatically creates (or, on a later test, adjusts) a dedicated virtual proxy named kpimailer in your Qlik Sense environment, so KPImailer’s own sessions stay isolated from users browsing Qlik Sense directly through the default hub. Qlik Cloud verifies Server reachable and Authentication only, since Qlik Cloud has no virtual proxy concept - instead, the first successful test provisions a webhook subscription in the tenant (using the Use webhooks permission from above) so Qlik Cloud app reload alerts fire the moment a reload finishes, rather than KPImailer polling for it. Re-running Test connection later reuses the existing webhook instead of creating a duplicate.

4. Select Save.

5. Use Sync apps any time to pull newly published apps into the Qlik Repository without waiting for the next automatic sync.

When to change this

• Rotating credentials - replace the client certificate (on-premise) or the OAuth client secret (Qlik Cloud) before the old one expires, and test the connection before relying on it.
• A Qlik admin changes the service account or its permissions - update Service account user / User directory (on-premise) or the OAuth client (Cloud) to match.
• Reports are slow or timing out under load - lower Max parallel executions if the Qlik server itself is struggling to keep up with concurrent extractions; raise it if the server has headroom and reports are queuing unnecessarily.

Worked example

A certificate used for the on-premise connection is due to expire next week. An administrator generates a new client certificate on the Qlik Sense server, opens Settings → Qlik servers → Edit on the on-premise entry, uploads the new .pfx file with Upload certificate, enters its password, and selects Test connection - all five checks pass, so they save with confidence before the old certificate expires.

A Qlik Cloud tenant is being connected for the first time. A Qlik Cloud administrator creates the OAuth client and Web integration following Setting up Qlik Cloud access, pastes all three values into Settings → Qlik servers → Edit, and selects Test connection - both checks pass. Before relying on it, they open Manage users in Qlik Cloud, find the new bot user, and swap its default Tenant Admin role for Analytics Admin plus the webhooks custom role, then re-run Test connection to confirm it still authenticates.

What can go wrong

Caution

If RootAdmin fails on a test connection, the service account lacks the Qlik Sense RootAdmin role needed for KPImailer to manage tasks and read every app - ask your Qlik administrator to grant it before reports relying on this server will work reliably.

Caution

An invalidated client certificate (on-premise) or a rotated/revoked OAuth secret (Qlik Cloud) doesn’t fail loudly until the next sync or report run - if reports against one server start failing together, check that server’s Test connection result first.

Caution

If a Qlik Cloud connection fails Authentication even though the Client ID, secret, and Web integration ID all look correct, check the OAuth client’s consent method in Qlik Cloud - an M2M client left on its default consent method (rather than Trusted) can’t authenticate without a user present, which shows up in KPImailer as an authentication failure.