Skip to main content
This guide shows how to:
  • Connect Timbal to Qlik Cloud with only a tenant URL, a client ID and a client secret
  • Choose between personal access (each user’s own Qlik permissions) and service access (one machine identity)
  • Give an agent the Qlik tools and the instructions to use them
The complete example lives in examples/qlik.

The tools

Setup Requirements

websockets is needed by qlik_query only (the Engine API is a websocket). It also comes with timbal[server].
1

Open the OAuth settings

With the Tenant Admin role, open https://<tenant>.<region>.qlikcloud.com and go to Administration > Integration > OAuth. Click Create new.
2

Configure the client

  1. Client type: Web
  2. Name: for example Timbal agent
  3. Scopes: user_default, plus offline_access for personal mode (it yields a refresh token)
  4. Redirect URLs (personal mode): http://localhost:8765/callback, plus your app’s own callback if it signs users in
3

Service mode only: allow machine-to-machine

Enable Allow Machine-to-Machine (M2M) and set the consent method to Trusted.
Without both, Qlik refuses the client_credentials grant with OAUTH-5. The tools name this requirement in the error.
4

Copy the credentials

Click Create, then copy the client ID and the client secret. The secret is shown only once.

Choose an Authentication Method

Use this if each person should see only what their own Qlik roles, spaces and Section Access allow.The tools send that person’s access token, so Qlik enforces their permissions. Locally, sign in once with the example’s script:
It opens the Qlik sign-in page, catches the redirect on http://localhost:8765/callback, and saves the tokens to .qlik_token.json (readable by you only). .env then needs:
The tools exchange the refresh token for access tokens as needed. Qlik can rotate refresh tokens on each use, so the newest one is written back to the token file; without the file it would live only in memory and a restart would reuse a spent token. On the Timbal platform, a personal Qlik integration supplies the user’s access token instead (pass integration=). The platform refreshes it and keeps the rotated refresh token, so the tools never exchange an integration’s refresh token themselves.

Building the Agent

The Qlik tools read their credentials from the environment, so adding them is enough:
fragment
A typical answer takes three calls:
fragment
dimensions are field names (or =expressions); measures are Qlik expressions, and filters go inside them as set analysis. Measures come back as numbers, dimensions as Qlik’s display text, and truncated says whether more rows exist than max_rows.

Shipping the instructions as a Skill

The example packages the tools and their instructions as a Skill: skills/qlik/SKILL.md tells the agent how to explore an app, write set analysis and respect permission boundaries, and skills/qlik/tools/qlik_tools.py creates the four tools. Copy the folder into your project and point the agent at it:
fragment

Configuration Reference

Every tool takes the same optional fields, which win over the environment:
When mode is not set, a person’s token is tried before the service credentials. Set mode="personal" wherever a user without a Qlik sign-in must be refused rather than answered through the service identity. An integration that carries a user’s token is treated as personal unless it sets mode.

Troubleshooting