API Keys & Tokens

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)	Short-lived token for authenticating API requests	Token endpoint (client credentials grant)	~24 hours
Session Token	Short-lived token identifying the current merchant and user	App Shell (via AppBridge)	Short-lived
API Key (OnPremise)	Permanent key for local ERP API access	JTL-Wawi desktop registration flow	Permanent
SCX Auth Token	Short-lived token for SCX Channel API requests	SCX auth endpoint	~1 hour

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:

Log in to the Partner Portal
Click the + Create button. You’ll see a registration wizard
Fill in the details or use the JSON Code Editor to paste the contents of your app.json file
Click the app and copy the new Client Secret
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": 86399,
	"scope": "",
	"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 (86399 ≈ 24 hours)
`scope`	string	The granted scopes
`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 24 hours (expires_in: 86399). 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.

Session Token

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.

Decoded Structure

A session token is a JWT with three parts: header, payload, and signature.

{
	"header": {
		"alg": "EdDSA",
		"typ": "JWT"
	},
	"payload": {
		"exp": 1746616503,
		"userId": "<UUID>",
		"tenantId": "<UUID>",
		"tenantSlug": "<string>"
	},
	"signature": "fwjol6pXYkS7sXQ..."
}

Field	Value	Description
`alg`	`EdDSA`	Edwards-curve Digital Signature Algorithm (the signing algorithm)
`typ`	`JWT`	Standard JWT type identifier

Payload

Field	Type	Description
`exp`	number	Expiration timestamp (Unix time). The token is invalid after this time
`userId`	string (UUID)	Unique identifier of the authenticated user
`tenantId`	string (UUID)	Identifier of the merchant’s tenant. Send this as the `X-Tenant-ID` header on every ERP API request
`tenantSlug`	string	Human-readable tenant identifier

Signature

The signature ensures the token has not been tampered with. Your backend verifies it using JTL’s public keys, fetched from the JWKS endpoint.

Verification

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 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	Session Token	API Key	SCX Auth Token
Used by	Cloud apps (backend)	Cloud apps (frontend to backend)	OnPremise apps	Marketplace channels
Format	JWT (Bearer)	JWT (EdDSA)	UUID	JWT (Bearer)
Lifetime	~24 hours	Short-lived	Permanent	~1 hour
How to get	Client credentials grant	AppBridge (`getSessionToken`)	Wawi registration	SCX auth endpoint
Refresh mechanism	Re-request with credentials	Re-request via AppBridge	N/A (permanent)	Re-request with credentials
Verify server-side?	No (trusted issuer)	Yes (JWKS)	N/A (you created it)	No (trusted issuer)

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 Cloud Apps: Authentication & Login.

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.

What’s Next?

OAuth 2.0 Flow

How to obtain access tokens, API keys, and SCX auth tokens.

Cloud Apps: Authentication

Implementation guide for session tokens, AppBridge, and the setup handshake in Cloud Apps.

Error Handling

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

Essentials

Cloud Apps

Marketplace Channels

ERP Integration

Vouchers API

Credentials and Tokens at a Glance

Client Credentials

Client ID

Client Secret

Regenerating a Lost Secret

Storage Best Practices

Access Token (JWT)

Token Response

Using the Access Token

Token Lifecycle

Session Token

Decoded Structure

Header

Payload

Signature

Verification

API Key (OnPremise)

Key Characteristics

Token Comparison

Inspecting Tokens for Debugging

What’s Next?

OAuth 2.0 Flow

Cloud Apps: Authentication

Error Handling

​Credentials and Tokens at a Glance

​Client Credentials

​Client ID

​Client Secret

​Regenerating a Lost Secret

​Storage Best Practices

​Access Token (JWT)

​Token Response

​Using the Access Token

​Token Lifecycle

​Session Token

​Decoded Structure

​Header

​Payload

​Signature

​Verification

​API Key (OnPremise)

​Key Characteristics

​Token Comparison

​Inspecting Tokens for Debugging

​What’s Next?

OAuth 2.0 Flow

Cloud Apps: Authentication

Error Handling

Credentials and Tokens at a Glance

Client Credentials

Client ID

Client Secret

Regenerating a Lost Secret

Storage Best Practices

Access Token (JWT)

Token Response

Using the Access Token

Token Lifecycle

Session Token

Decoded Structure

Header

Payload

Signature

Verification

API Key (OnPremise)

Key Characteristics

Token Comparison

Inspecting Tokens for Debugging

What’s Next?