API Keys & Tokens

Manage API keys, app 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.

Credentials and Tokens at a Glance

Credential / Token	What it is	Where you get it	Lifetime
Client ID	Your app’s public identifier	Partner Portal (after registration)	Permanent (can regenerate)
Client Secret	Your app’s private key for authentication	Partner Portal (shown once at registration)	Permanent (can regenerate)
Access Token (JWT)	Token authenticating your backend’s own API requests	Token endpoint (client credentials grant)	~1 hour
App Token (JWT)	Token identifying the current merchant and tenant	AppBridge, or browser sign-in	~1 hour
API Key (OnPremise)	Permanent key for local ERP API access	JTL-Wawi desktop registration flow	Permanent

Client Credentials

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.

Client ID

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.

Client Secret

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.

Regenerating a Lost Secret

The Partner Portal does not currently support in-place secret rotation. To regenerate, register a new app with the same manifest:

1. Log in to the Partner Portal
2. Click the + Create button. You’ll see a registration wizard
3. Fill in the details or use the JSON Code Editor to paste the contents of your app.json file
4. Click the app and copy the new Client Secret
5. Update the secret in your app’s environment variables and redeploy.

Storage Best Practices

Do	Don’t
Store in environment variables (.env, .env.local)	Hardcode in source code
Use a secrets manager in production (AWS Secrets Manager, HashiCorp Vault, etc.)	Commit .env files to version control
Restrict access to credentials to team members who need them	Share credentials in chat, email, or tickets
Rotate the secret if you suspect it’s been compromised	Reuse the same credentials across multiple apps

Access Token (JWT)

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.

Token Response

When you request an access token, JTL returns:

{
	"access_token": "eyJhbGciOiJSUzI1NiIsImt.......",
	"expires_in": 3599,
	"id_token": "eyJhbGciOiJSUzI1NiIsImt.......",
	"token_type": "bearer"
}

Field	Type	Description
access_token	string	The JWT to include in API request headers
expires_in	number	Seconds until the token expires (3599 ≈ 1 hour)
id_token	string	The JWT containing information about the authenticated user
token_type	string	Always bearer: include as Authorization: Bearer <token>

Using the Access Token

Include it in the Authorization header of every API request:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImt.......

Token Lifecycle

Access tokens expire in approximately 1 hour (expires_in: 3599). Handle this as follows:

• Cache the token: Don’t request a new one for every API call
• Track expiry: Store the expires_in value and request a new token before it expires (for example, when less than 5 minutes remain)
• Handle 401 responses: A 401 Unauthorized response typically means the token has expired. Request a new one and retry the request once.

App Token

App tokens identify which merchant and tenant is using your app. An app running inside the Cloud ERP gets one from the AppBridge. An app running on its own domain gets one by signing the merchant in against the platform identity provider.

For implementation details, see App Token Authentication.

Decoded Structure

An app token is a JWT with three parts: header, payload, and signature.

{
  "header": {
    "alg": "RS256",
    "kid": "380142387634218738",
    "typ": "JWT"
  },
  "payload": {
    "aud": ["389707023228376722", "5aa3624f-2236-4e5b-b7e5-7091be7764f0"],
    "client_id": "389707023228376722",
    "exp": 1788865347,
    "iat": 1788861747,
    "iss": "https://id.jtl-cloud.com",
    "jti": "V2_389845033982945061-at_389845033983010597",
    "nbf": 1788861747,
    "sub": "0292bace-2568-4722-a6fc-50023ca1650a",
    "urn:jtl:api_scopes": ["orders.read", "orders.write"],
    "urn:jtl:kundencenter_id": "1348883",
    "urn:jtl:tenant_id": "73bd3d84-f7e3-46c6-ba52-a870c76b9ee7"
  },
}

Header

Field	Value	Description
alg	RS256	RSA signature with SHA-256
kid	string	Identifies which key in the JWKS signed this token
typ	JWT	Standard JWT type identifier

Payload

Field	Type	Description
aud	array of string	Audience. Contains your app ID.
client_id	string	The OIDC client the token was issued to
exp	number	Expiration timestamp in Unix seconds
iat	number	Issue timestamp in Unix seconds
iss	string	The issuing identity provider
jti	string	Unique token identifier
nbf	number	Not-before timestamp in Unix seconds
sub	string (UUID)	The signed-in merchant’s user ID
urn:jtl:api_scopes	array of string	The API scopes this user holds on your app, as resource.permission strings (see Scopes & permissions). Absent if your app declares no scopes.
urn:jtl:tenant_id	string (UUID)	The merchant’s tenant. Send this as the X-Tenant-ID header on backend API calls.
urn:jtl:kundencenter_id	string	The merchant’s JTL customer account number

Verification

App tokens must be verified server-side before any claim is trusted:

• Fetch the identity provider’s public keys from ${issuer}/oauth/v2/keys. No credentials are needed.
• Select the key whose kid matches the token header, and verify the signature
• Confirm the issuer matches, and that exp is present and in the future
• Confirm aud contains your app ID, so a token minted for another app is rejected

Never trust an app token without verifying it server-side. A token received from the client could be tampered with or minted for a different app. Verify the signature and the audience before acting on the payload.

API Key (OnPremise)

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.

Key Characteristics

Property	Value
Format	UUID (e.g. 00000000-0000-0000-0000-000000000000)
Lifetime	Permanent (does not expire unless revoked)
Shown	Once, at the time of creation
Header format	Authorization: Wawi <API-Key>
Scope	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.

For the full OnPremise registration flow, see OAuth 2.0 Flow (OnPremise tab).

Token Comparison

	Access Token	App Token	API Key
Used by	Cloud apps (backend)	Cloud apps (frontend, and frontend to backend)	OnPremise apps
Format	JWT (Bearer)	JWT (Bearer, RS256)	UUID
Lifetime	~1 hour	~1 hour	Permanent
How to get	Client credentials grant	AppBridge (getAppToken) or browser sign-in	Wawi registration
Renewal	Re-request with credentials	Re-request via AppBridge, or refresh token	N/A (permanent)
Verify server-side?	No (your app requested it)	Yes (JWKS and audience)	N/A (you created it)

Inspecting Tokens for Debugging

During development, you may need to read a token’s contents to confirm what’s inside. For the verification flow that backends should use in production, see App Token Authentication.

For quick inspection during development, you can use jwt.io to decode a non-sensitive test token and view its header and payload. Never paste production tokens, credentials, or other sensitive data into third-party tools.

What’s Next?

OAuth 2.0 Flow

How to obtain access tokens and API keys.

App Token Authentication

Verify app tokens, read the tenant from their claims, and map merchants to your records.

Error Handling

How to handle auth errors, expired tokens, and 401 responses.