Manage API keys, session tokens, and JWTs for the JTL Platform
The JTL platform uses different credentials and tokens depending on the integration type and API. This page explains what each one is, when to use it, and how to manage it.To obtain these tokens, see the OAuth 2.0 Flow page.
Client credentials identify your app on the JTL platform. Every registered app receives a pair: a Client ID (public) and a Client Secret (private). Together, they’re used to request access tokens from JTL’s identity provider.
Your app’s public identifier. It’s safe to include in logs and non-sensitive contexts. The Partner Portal displays it on your app’s detail page, and you can view it at any time.
Your app’s private key, used alongside the Client ID to generate access token for your app. The Partner Portal displays it only once, immediately after registration.
The Client Secret is shown only once. Copy and store it securely at the
moment of registration. If you lose it, you’ll need to regenerate it.
The access token is what your backend uses to authenticate API requests to JTL. You obtain it by sending your client credentials to JTL’s token endpoint via the client credentials grant.
Session tokens are issued by the App Shell and identify which merchant (tenant) and user is currently interacting with your app. They are only relevant for Cloud Apps that run inside the App Shell.Unlike access tokens (requested by your app), session tokens come from the host environment. The App Shell passes them to your app through AppBridge, a lightweight SDK that handles session tokens, method calls, and events.For implementation details on retrieving and verifying session tokens, see Cloud Apps: Authentication & Login.
Session tokens must be verified server-side using JTL’s public keys:
Your backend requests an access token (client credentials grant)
Using that access token, it fetches JTL’s public keys from the JWKS endpoint (https://api.jtl-cloud.com/account/.well-known/jwks.json)
It uses the public key to verify the session token’s signature
If the signature is valid, the payload (tenantId, userId, etc.) can be trusted
Never trust a session token without verifying it server-side. A token
received from the client (frontend) could be tampered with. Always verify
the signature against the JWKS public key before acting on the payload.
API keys are permanent credentials used only in the OnPremise deployment model. They are generated through a two-step registration process in the JTL-Wawi desktop application.
Local to the Wawi installation where it was registered
Like the Client Secret, the API key is displayed only once during
registration. Store it securely immediately. If lost, you will need to go
through the registration process again.
During development, you may need to decode a JWT to inspect its contents:
import { jwtVerify, importJWK, decodeProtectedHeader } from 'jose';export async function verifySessionToken(sessionToken: string) { const response = await fetch( 'https://api.jtl-cloud.com/account/.well-known/jwks.json', ); if (!response.ok) { throw new Error(`Failed to fetch JWKS (${response.status})`); } const jwks = await response.json(); const { kid } = decodeProtectedHeader(sessionToken); if (!kid) { throw new Error('Missing kid'); } const jwk = jwks.keys.find((k: any) => k.kid === kid); if (!jwk) { throw new Error('No matching JWK'); } const publicKey = await importJWK(jwk, 'EdDSA'); const { payload } = await jwtVerify(sessionToken, publicKey, { algorithms: ['EdDSA'], issuer: 'https://api.jtl-cloud.com', }); return payload;}
For quick inspection during development, paste your token into
jwt.io. It decodes the header and payload instantly. Do
not paste production tokens or any sensitive credentials into third-party
tools.
