Authenticate with Private Key JWT

In this tutorial, you’ll learn how to use Private Key JWT to authenticate your OAuth client application to Qlik Cloud securely.

Instead of sharing a client secret, your application signs authentication requests with a private key, and Qlik Cloud validates them using your registered public key.

This approach is more secure and ideal for production environments.

What you’ll learn

How to generate a public/private key pair for OAuth authentication
How to register your public key with an OAuth client in Qlik Cloud
How to sign JWT assertions and request access tokens
How to use tokens to authenticate API requests

Prerequisites

A Qlik Cloud tenant with Tenant Admin access
OpenSSL installed on your development machine
A programming language with JWT signing libraries (JavaScript with jose or Python with PyJWT recommended)

How it works

Private Key JWT lets your application prove its identity using asymmetric cryptography instead of a shared secret:

You generate a public/private key pair and register the public key with your OAuth client in Qlik Cloud
Your application creates a JWT (JSON Web Token) signed with its private key
Your application sends the signed JWT to Qlik Cloud’s token endpoint
Qlik Cloud validates the signature using your registered public key and returns an access token
Your application uses the access token for API requests

The private key never leaves your application, making this approach more secure than sharing a client secret.

Step 1: Generate your key pair

Generate a public/private key pair that will be used to sign the JWT assertion and register the public key with your OAuth client.

Use OpenSSL to generate a 2048-bit RSA key pair (minimum requirement for RS256):

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

Warning

Keep your private key (private_key.pem file) secure and never share it. It is used to sign JWT assertions.

Convert the public key from PEM to JSON Web Key (JWK) format using the jose package:

import { exportJWK, importSPKI } from 'jose';
import { readFileSync } from 'node:fs';

const pem = readFileSync('public_key.pem', 'utf8');
const key = await importSPKI(pem, 'RS256');
const jwk = await exportJWK(key);
jwk.alg = 'RS256';
jwk.use = 'sig';
jwk.kid = 'my-key-1';
console.log(JSON.stringify(jwk, null, 2));

# Using a JWK library like python-jose or jwt
# This example uses python-cryptography + manual conversion
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.backends import default_backend
import json
import base64

with open('public_key.pem', 'rb') as f:
    public_key = serialization.load_pem_public_key(
        f.read(),
        backend=default_backend()
    )

# Export to JWK (consider using a library like python-jose for production)
numbers = public_key.public_numbers()
jwk = {
    "kty": "RSA",
    "alg": "RS256",
    "use": "sig",
    "kid": "my-key-1",
    "n": base64.urlsafe_b64encode(
        numbers.n.to_bytes(256, byteorder='big')
    ).decode().rstrip('='),
    "e": base64.urlsafe_b64encode(
        numbers.e.to_bytes(3, byteorder='big')
    ).decode().rstrip('='),
}
print(json.dumps(jwk, indent=2))

Save the JWK output. You’ll register it with your OAuth client in the next step.

Tip

For other algorithms (RS512, ES384), see Supported algorithms in the reference.

Step 2: Create and configure your Web OAuth client

Now that you have your public key in JWK format, create a new Web OAuth client and register it.

In the Administration activity center, go to OAuth.
Click Create new and select Web as the client type.
Enter a name.
Under Authentication method, select Private Key JWT.
Paste your JWK (from Step 1) into the Public key field.

Warning

Paste only the public key in JWK format. Never upload or share your private key.
Click Create.
Set the consent method to Trusted (click the action menu and select Change consent method).

Your OAuth client is now configured for Private Key JWT authentication. Copy your Client ID for use in the next step. Qlik Cloud will validate JWT signatures against this public key during token requests.

Step 3: Request an access token

Private Key JWT authentication requires two sub-steps: generate a signed JWT assertion, then exchange it for a token.

Generate the JWT assertion

Use your private key to create a signed JWT assertion:

import { SignJWT, importPKCS8 } from 'jose';
import { randomUUID } from 'node:crypto';
import { readFileSync } from 'node:fs';

const TENANT = '<TENANT>';
const CLIENT_ID = '<CLIENT_ID>';
const PRIVATE_KEY_PEM = readFileSync('private_key.pem', 'utf8');

try {
  const privateKey = await importPKCS8(PRIVATE_KEY_PEM, 'RS256');
  const now = Math.floor(Date.now() / 1000);

  const assertion = await new SignJWT({})
    .setProtectedHeader({ alg: 'RS256' })
    .setIssuer(CLIENT_ID)
    .setSubject(CLIENT_ID)
    .setAudience(`https://${TENANT}.qlikcloud.com/oauth/token`)
    .setJti(randomUUID())
    .setIssuedAt(now)
    .setExpirationTime(now + 300)
    .sign(privateKey);

  console.log(assertion);
} catch (error) {
  console.error('Failed to generate JWT:', error.message);
}

import time
import uuid
import jwt

TENANT = '<TENANT>'
CLIENT_ID = '<CLIENT_ID>'

try:
    with open('private_key.pem', 'rb') as f:
        private_key = f.read()

    now = int(time.time())
    payload = {
        'iss': CLIENT_ID,
        'sub': CLIENT_ID,
        'aud': f'https://{TENANT}.qlikcloud.com/oauth/token',
        'jti': str(uuid.uuid4()),
        'iat': now,
        'exp': now + 300,
    }
    assertion = jwt.encode(payload, private_key, algorithm='RS256')

    print(assertion)
except Exception as error:
    print(f'Failed to generate JWT: {error}')

Copy the output (your signed JWT assertion). You’ll use this in Step 2.

Exchange the assertion for a token

Send your JWT assertion to the Qlik Cloud token endpoint. Use one of the methods below:

const TENANT = '<TENANT>';
const CLIENT_ID = '<CLIENT_ID>';
const assertion = '<SIGNED_JWT_ASSERTION>';  // From previous step

try {
  const response = await fetch(
    `https://${TENANT}.qlikcloud.com/oauth/token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: CLIENT_ID,
        client_assertion_type:
          'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
        client_assertion: assertion,
        scope: 'user_default',
      }),
    }
  });

  if (!response.ok) {
    throw new Error(`Token request failed: ${response.status} ${response.statusText}`);
  }

  const data = await response.json();
  console.log(data.access_token);
} catch (error) {
  console.error('Authentication failed:', error.message);
}

import requests

TENANT = '<TENANT>'
CLIENT_ID = '<CLIENT_ID>'
assertion = '<SIGNED_JWT_ASSERTION>'  # From previous step

try:
    response = requests.post(
        f'https://{TENANT}.qlikcloud.com/oauth/token',
        data={
            'grant_type': 'client_credentials',
            'client_id': CLIENT_ID,
            'client_assertion_type': 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
            'client_assertion': assertion,
            'scope': 'user_default',
        },
    )

    if response.status_code != 200:
        raise Exception(f'Token request failed: {response.status_code} {response.reason}')

    print(response.json()['access_token'])
except Exception as error:
    print(f'Authentication failed: {error}')

curl -X POST https://<TENANT>.qlikcloud.com/oauth/token ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  -d "grant_type=client_credentials" ^
  -d "client_id=<CLIENT_ID>" ^
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" ^
  -d "client_assertion=<SIGNED_JWT_ASSERTION>" ^
  -d "scope=user_default"

A successful response returns your access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "user_default"
}

Use the token in API requests

Add your access token to the Authorization header:

const response = await fetch(`https://${TENANT}.qlikcloud.com/api/v1/users/me`, {
  headers: {
    'Authorization': `Bearer ${access_token}`,
  },
});
const user = await response.json();
console.log(user);

response = requests.get(
    f'https://{TENANT}.qlikcloud.com/api/v1/users/me',
    headers={'Authorization': f'Bearer {access_token}'}
)
print(response.json())

curl -X GET https://<TENANT>.qlikcloud.com/api/v1/users/me \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Troubleshooting

Issue	Cause	Solution
Signature validation failed	Public key doesn’t match private key or algorithm mismatch	Verify the algorithm in JWT header (`alg`) matches your registered key (RS256, RS512, ES384). Regenerate and re-register the key pair if needed.
Invalid audience	`aud` claim doesn’t match token endpoint URL	Ensure `aud` is exactly `https://<TENANT>.qlikcloud.com/oauth/token` with no trailing slashes
Invalid client or unauthorized_client	`iss`/`sub` claims don’t match CLIENT_ID or client doesn’t exist	Verify both `iss` and `sub` are set to your actual CLIENT_ID. Confirm the OAuth client exists and is enabled.
unsupported_client_assertion_type	Wrong parameter value	Ensure `client_assertion_type` is exactly `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
Token request timeout	Network issue or tenant unreachable	Verify network connection and test tenant URL: `curl https://<TENANT>.qlikcloud.com`

For detailed troubleshooting and security recommendations, see Private Key JWT reference.

Next steps

Private Key JWT reference: Algorithms and JWK specifications
OAuth tokens API: Reference for token endpoint parameters and responses
Create an OAuth2 client: Set up a new OAuth client
OAuth scopes: Understand permissions and scope requirements