OAuth 2.0 Flow

How authentication works on the JTL platform: Cloud OAuth 2.0, OnPremise API keys, and refresh tokens.

The JTL platform uses different authentication mechanisms across its APIs. This page explains how each one works, when to use it, and how tokens are managed.

Authentication at a Glance

API	Auth mechanism	Token type	Lifetime
JTL Cloud API (machine)	OAuth 2.0 Client Credentials	JWT access token	~1 hour
JTL Cloud API (user)	AppBridge or browser sign-in	JWT app token	~1 hour
OnPremise ERP API	Proprietary registration flow	Static API key	Permanent

Two Types of Tokens (Cloud)

Cloud Apps use two tokens, each answering a different question.

Token	How you get it	What it’s for	Who creates it
App token	appBridge.method.call('getAppToken'), or browser sign-in on your own domain	Identifying which merchant and tenant is using your app	JTL Identity Provider
Access token	Client credentials grant against the JTL Identity Provider	Authenticating your backend’s own API calls	Your app’s backend

The app token identifies the merchant. The access token authorizes your app.

An app with a backend uses both: it verifies the app token to learn which tenant a request belongs to, then calls the API with its access token. An app without a backend calls the API with the app token directly.

See App Token Authentication for verification and tenant mapping, and Service Account Authentication for the client credentials implementation.

JTL Cloud (OAuth 2.0)

Cloud Authentication (OAuth 2.0)

The Cloud API uses the OAuth 2.0 Client Credentials Flow. Your app’s backend authenticates with a client ID and secret, receives a short-lived JWT, and uses that JWT as a Bearer token for all API requests.

Prerequisites

Your app must be registered in the Partner Portal. Registration creates an OAuth client with a Client ID and Client Secret.

Your Client Secret is displayed only once immediately after registration. Store it securely.

How the Flow Works

1. Your backend sends its client credentials to the JTL Identity Provider
2. The Identity Provider returns a short-lived JWT access token
3. Your backend includes that token (along with the tenant ID) in every API request

Token Endpoint

POST https://id.jtl-cloud.com/oauth/v2/token

Request:

Component	Value
Method	POST
Content-Type	application/x-www-form-urlencoded
Authorization	Basic <Base64(clientId:clientSecret)>
Body	grant_type=client_credentials

Example request:

cURL

curl -X POST 'https://id.jtl-cloud.com/oauth/v2/token' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'scope=openid'

Response:

{
	"access_token": "eyJhbGciOiJSUzI1NiIs...",
	"token_type": "Bearer",
	"expires_in": 3599,
	"id_token": "eyJhbGciOiJSUzI1NiIs..."
}

Field	Description
access_token	The JWT to use in API requests
token_type	Always Bearer
expires_in	Token lifetime in seconds. Request a new token before this expires.
id_token	The JWT containing information about the authenticated user

For a full implementation including caching and retry, see Service Account Authentication.

Making Authenticated API Requests

Once you have an access token, include it in every API request along with the tenant ID.

Base URL:

https://api.jtl-cloud.com/erp/v2/

Required headers:

Header	Value	Description
Authorization	Bearer <JWT>	The access token from the client credentials flow
X-Tenant-ID	<tenantId>	The JTL Cloud tenant ID (identifies which merchant’s data you’re accessing)

Example request:

curl -X GET https://api.jtl-cloud.com/erp/v2/info \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID"

The tenant ID comes from the urn:jtl:tenant_id claim of a verified app token. See App Token Authentication.

Token Lifecycle

Access tokens last approximately 1 hour. Your app needs to handle expiry:

• Cache the token and reuse it until it is close to expiry
• Request a new one before the current token expires, rather than waiting for a failure
• Handle 401 Unauthorized by requesting a new token once and retrying

Security Schemes

Cloud endpoints are secured using one of two schemes:

Scheme	When it applies
Wawi AND oauth2-cloud-id-accessCode	User-bound access: the request is tied to a specific user’s session
Wawi AND oauth2-application	Machine-to-machine access: your backend calls the API directly using client credentials

OnPremise (API Key)

OnPremise Authentication

The OnPremise API uses a proprietary two-step registration flow that produces a permanent API key (no OAuth).

This applies when your app integrates directly with a merchant’s local JTL-Wawi installation.

Base URL:

http://127.0.0.1:<port>/api/eazybusiness/

How the Flow Works

Registration Steps

1. Prepare for Registration in JTL-Wawi

   In the JTL-Wawi desktop application, navigate to Admin > App Registration and complete the required steps. The steps must be completed before your app can send its first API request. The registration endpoint is not available until it’s done.

2. Register your App (POST)

   Send a POST request with your app’s information to the authentication endpoint.

   Endpoint:

   POST http://127.0.0.1:<port>/api/eazybusiness/authentication
   

   Required headers:

   Header	Description
   api-version	Desired API version, e.g. 2.0
   x-challengecode	A custom value of your choice (max 30 characters). Must be identical across all registration requests.

   Required body fields:

   Field	Description
   AppName	Name of your application
   AppVersion	Version of your application
   RequiredApiScopes	API scopes your app needs
   AppIcon	Base64-encoded app icon
   RegistrationType	0 = OneInstance, 1 = MultiInstance, 2 = PerUserInstance, 3 = PerUserLoginInstance

   Example request:

   cURL

   curl -X POST "http://127.0.0.1:<port>/api/eazybusiness/authentication" \
     -H "Content-Type: application/json" \
     -H "api-version: 2.0" \
     -H "x-challengecode: my-custom-challenge" \
     -d '{
       "AppName": "My App",
       "AppVersion": "1.0.0",
       "RequiredApiScopes": ["<scope1>", "<scope2>"],
       "AppIcon": "iVBORw0KGgoAAAANSUhEUgAA...",
       "RegistrationType": 0
     }'
   

   RequiredApiScopes follows the resource.read and resource.write pattern (e.g. orders.read, orders.write, products.read, products.write, etc.).

   The API responds with a registration ID (token).

3. Confirm and Retrieve API Key (GET)

   After receiving the registration ID, the user will be prompted to confirm the registration in JTL-Wawi. Once confirmed, your app sends a GET request with the registration ID:

   Endpoint:

   GET http://127.0.0.1:<port>/api/eazybusiness/authentication/{registrationId}
   

   Required headers:

   Header	Description
   api-version	Desired API version
   x-challengecode	The same value used in the previous step

   Example request:

   cURL

   curl -X GET "http://127.0.0.1:<port>/api/eazybusiness/authentication/{registrationId}" \
     -H "api-version: 2.0" \
     -H "x-challengecode: my-custom-challenge"
   

   On success, the API returns a permanent API key.

   The API key is returned only once and cannot be retrieved again. Store it securely.

4. Make Authenticated API Requests

   Include the API key in the Authorization header of every request.

   Required headers:

   Header	Value	Description
   Authorization	Wawi <API-Key>	The permanent API key from registration
   x-appid	e.g. MyApp/1.0.0	Name of your application
   x-appversion	e.g. 1.0.0	Version of your application
   api-version	e.g. 2.0	Desired API version
   x-challengecode	Custom value	The same value used during registration
   x-runas (optional)	User ID (int or UUID)	Execute request on behalf of a Wawi user. Requires Application.RunAs scope.

   Example request:

   cURL

   curl -i -X GET \
     'http://127.0.0.1:<port>/api/eazybusiness/info' \
     -H 'Authorization: Wawi <PERMANENT_API_KEY>' \
     -H 'api-version: 2.0' \
     -H 'x-appid: MyApp/1.0.0' \
     -H 'x-appversion: 1.0.0' \
     -H 'x-challengecode: my-custom-challenge'
   

JTL Cloud vs. OnPremise Comparison

Feature	Cloud	OnPremise
Auth mechanism	OAuth 2.0 (Client Credentials)	Proprietary API key flow
Token type	Short-lived JWT Bearer token	Permanent static API key
Registration	Partner Portal	JTL-Wawi desktop Admin >> App Registration
Credentials	ClientId + ClientSecret	Registration ID >> API key
Tenant identification	X-Tenant-ID header required	Not required (local connection)
Base URL	https://api.jtl-cloud.com/erp/v2/	http://127.0.0.1:<port>/api/eazybusiness/
Authorization format	Bearer <JWT>	Wawi <PERMANENT_API_KEY>
Token refresh	Re-request with client credentials before expiry	Not needed (key is permanent)

---

Best Practices

These practices apply regardless of which auth mechanism you’re using:

Credential storage

• Never hardcode credentials in source code. Use environment variables or a secrets manager.
• Never commit .env files to version control.
• Rotate credentials if you suspect they’ve been compromised.

Token management

• Cache tokens and reuse them. Don’t request a new token for every API call.
• Refresh proactively before expiry, not after receiving a 401 error.
• On a 401 response, refresh the token and retry the request once.

Security

• Always use HTTPS for Cloud API calls.
• Verify app tokens server-side. Never trust a token received from the client without checking its signature and audience.
• Request the minimum required scopes. Don’t request broader access than your app needs.

What’s Next?

API Keys & Tokens

Deeper dive into JWT structure, app tokens, and token management patterns.

App Token Authentication

Verify the app token in your backend and read the tenant from its claims.

Error Handling

How to handle auth errors, expired tokens, and common failure modes.