OAuth 2.0 Flow

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	OAuth 2.0 Client Credentials	Short-lived JWT	~1 hour (refresh before expiry)
OnPremise ERP API	Proprietary registration flow	Static API key	Permanent
SCX Channel API	Refresh token exchange	Short-lived access token	~1 hour (refresh before expiry)

Two Types of Tokens (Cloud)

If you’re building on the Cloud platform, you’ll use two tokens:

Token	How you get it	What it’s for	Who creates it
Access token (JWT)	Client credentials grant > JTL Identity Provider	Authenticating your backend’s API calls to JTL	Your app’s backend
Session token	`appBridge.method.call('getSessionToken')`	Identifying which merchant (tenant) and user is interacting with your app	JTL App Shell (via AppBridge)

Access token: identifies your app (machine-to-machine). Session token: identifies the tenant and user (from the App Shell). In a typical Cloud App, both tokens are in play: the session token tells you who, and the access token lets you act on their behalf.

Check out the Cloud Apps: Authentication & Login guide to learn more about Cloud Apps authentication (JWKS, AppBridge integration).

JTL Cloud (OAuth 2.0)
OnPremise (API Key)

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

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

Token Endpoint

POST https://auth.jtl-cloud.com/oauth2/token

Request:

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

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

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.

Reference Examples

async function getAccessToken(): Promise<string> {
  const clientId = process.env.CLIENT_ID;
  const clientSecret = process.env.CLIENT_SECRET;
 
  if (!clientId || !clientSecret) {
    throw new Error('CLIENT_ID and CLIENT_SECRET must be defined');
  }
 
  const authString = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
 
  const response = await fetch('https://auth.jtl-cloud.com/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${authString}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
    }),
  });
 
  const data = await response.json();
 
  if (response.ok) {
    return data.access_token;
  } else {
    throw new Error(`Failed to fetch token (${response.status}): ${data.error}`);
  }
}

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:

const accessToken = await getAccessToken();
 
const response = await fetch('https://api.jtl-cloud.com/erp/v2/info', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'X-Tenant-ID': tenantId,
  },
});

Check out the Cloud Apps: Authentication & Login guide to see how to get the tenant ID.

Token Lifecycle

Access tokens are short-lived and expire after a set period (typically 1 hour). Your app needs to handle this:

Cache the token and reuse it until it’s close to expiry
Refresh proactively (e.g. when < 5 minutes remain)
Handle 401 Unauthorized by refreshing 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 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

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.

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

const response = await fetch(
  "http://127.0.0.1:<port>/api/eazybusiness/authentication",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "api-version": "2.0",
      "x-challengecode": "my-custom-challenge",
    },
    body: JSON.stringify({
      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).

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

const registrationId = "your-registration-id";

const response = await fetch(
  `http://127.0.0.1:<port>/api/eazybusiness/authentication/${registrationId}`,
  {
    method: "GET",
    headers: {
      "api-version": "2.0",
      "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.

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.

const response = await fetch(
  "http://127.0.0.1:<port>/api/eazybusiness/info",
  {
    method: "GET",
    headers: {
      "Authorization": "Wawi <PERMANENT_API_KEY>",
      "api-version": "2.0",
      "x-appid": "MyApp/1.0.0",
      "x-appversion": "1.0.0",
      "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)

SCX Channel API Authentication

The SCX Channel API uses the same client credentials mechanism as the Cloud-ERP API. You request an access token, use it for API calls, and request a new one before it expires. This section applies only to Marketplace Channel integrations. Base URL:

https://scx.api.jtl-software.com/v1/

How the Flow Works

Requesting an Access Token

const formData = new FormData();
formData.append('refreshToken', 'YOUR-REFRESH-TOKEN');

const response = await fetch('https://scx.api.jtl-software.com/v1/auth', {
	method: 'POST',
	body: formData,
});

Response:

{
  "scope": "CHANNEL",
  "authToken": "eyJ0eXAi....",
  "tokenExpireAt": "2024-05-14T10:07:42+02:00",
  "expiresIn": 3600
}

Field	Description
`scope`	The scope of the token (e.g. `CHANNEL`)
`authToken`	The access token for authenticating requests
`tokenExpireAt`	Expiration timestamp in ISO 8601 format
`expiresIn`	Time in seconds until the token expires

Using the Access Token

Include the authToken as a Bearer token in all subsequent requests:

const response = await fetch("https://scx.api.jtl-software.com/v1/seller/channel/MYCHANNEL", {
  method: "POST",
  headers: {
    "Authorization": "Bearer eyJ0eXAi....",
  },
});

Token Lifecycle

SCX access tokens have a TTL (Time To Live) of 1 hour. Your app should:

Cache the token and reuse it until it’s close to expiry
Monitor the expiresIn value and refresh proactively (e.g. when less than 5 minutes)
Refresh tokens before they expire to avoid failures during requests.

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 and SCX API calls.
Validate session tokens server-side. Never trust tokens received from the client without verification.
Request the minimum required scopes. Don’t request broader access than your app needs.

Next Steps

API Keys & Tokens

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

Scopes & Permissions

Understand which scopes are available and how to request the right level of access.

Cloud Apps: Authentication

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

Error Handling

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

Essentials

Cloud Apps

Marketplace Channels

ERP Integration

Authentication at a Glance

Two Types of Tokens (Cloud)

Cloud Authentication (OAuth 2.0)

Prerequisites

How the Flow Works

Token Endpoint

Reference Examples

Making Authenticated API Requests

Token Lifecycle

Security Schemes

OnPremise Authentication

How the Flow Works

Registration Steps

JTL Cloud vs. OnPremise Comparison

SCX Channel API Authentication

How the Flow Works

Requesting an Access Token

Using the Access Token

Token Lifecycle

Best Practices

Next Steps

API Keys & Tokens

Scopes & Permissions

Cloud Apps: Authentication

Error Handling

Essentials

Cloud Apps

Marketplace Channels

ERP Integration

​Authentication at a Glance

​Two Types of Tokens (Cloud)

​Cloud Authentication (OAuth 2.0)

​Prerequisites

​How the Flow Works

​Token Endpoint

​Reference Examples

​Making Authenticated API Requests

​Token Lifecycle

​Security Schemes

​OnPremise Authentication

​How the Flow Works

​Registration Steps

​JTL Cloud vs. OnPremise Comparison

​SCX Channel API Authentication

​How the Flow Works

​Requesting an Access Token

​Using the Access Token

​Token Lifecycle

​Best Practices

​Next Steps

API Keys & Tokens

Scopes & Permissions

Cloud Apps: Authentication

Error Handling

Authentication at a Glance

Two Types of Tokens (Cloud)

Cloud Authentication (OAuth 2.0)

Prerequisites

How the Flow Works

Token Endpoint

Reference Examples

Making Authenticated API Requests

Token Lifecycle

Security Schemes

OnPremise Authentication

How the Flow Works

Registration Steps

JTL Cloud vs. OnPremise Comparison

SCX Channel API Authentication

How the Flow Works

Requesting an Access Token

Using the Access Token

Token Lifecycle

Best Practices

Next Steps