Skip to main content

​
What is a JTL Cloud App?

A JTL app is a software application that connects to JTL products or services through the API infrastructure. Apps can:
  • Extend the functionality of JTL products
  • Integrate in JTL products
  • Provide specialized processes or tools for specific business needs
  • Automate workflows between JTL and other systems
Every Cloud App consists of two components:
  • Frontend: your app’s UI, rendered inside an iframe within the JTL ERP Cloud. Built with any web framework (React, Vue, or plain HTML).
  • Backend: your server-side code that authenticates with JTL’s Identity Provider, calls the JTL Cloud and JTL-Wawi API, and serves your frontend.
The frontend communicates with the JTL Cloud host application through AppBridge, a bidirectional messaging layer built on postMessage. Your backend authenticates independently using OAuth 2.0 client credentials and calls the JTL Cloud API with a JWT access token.

​
Integration Types

Cloud Apps support four integration types. Each type determines where your app appears, how it communicates, and what kind of experience it provides.
TypeUICommunicationUse case
Hub-LinkCard in JTL HubRedirect to your URLEntry points, external tools, dashboards
ERP-iFrameEmbedded in ERP main contentAppBridge messagesRich interactive UI within the ERP
PaneSidebar in ERPAppBridge messagesContext-aware panels (e.g., customer detail sidebar)
HeadlessNoneDirect API callsBackend-to-backend automation, data sync
All four types require a manifest.json and app registration through the Partner Portal. A Hub-Link app adds a card to the JTL Hub dashboard. When a merchant clicks it, the platform redirects them to your appLauncher.redirectUrl. This is the simplest integration type: no iframe, no AppBridge, just a redirect. Hub-Link Use Hub-Link for external dashboards, standalone tools, or apps that don’t need to render inside the JTL UI. 
{
	"capabilities": {
		"hub": {
			"appLauncher": {
				"redirectUrl": "https://your-app.example.com/dashboard"
			}
		}
	}
}

​
ERP-iFrame

An ERP-iFrame app renders inside the main content area of ERP Cloud. Your frontend loads in an iframe and communicates with the host through the AppBridge. You define where your app appears using menuItems in the manifest, which adds entries to the ERP sidebar under App menu item. ERP-iFrame This is the most common integration type for apps that require a rich, interactive UI within the merchant’s ERP workspace. 
{
	"capabilities": {
		"erp": {
			"menuItems": [
				{
					"id": "my-app-menu",
					"name": "My JTL App",
					"url": "https://your-app.example.com/erp"
				}
			]
		}
	}
}
Example: An app that fetches product details from the ERP, sends them to an external AI service to generate descriptions, and lets the merchant push the result back to the product field with a button click.

​
Pane

A Pane app renders as a sidebar panel on the right side of the ERP content area. Like ERP-iFrame apps, Panes have full access to the AppBridge. The difference is purely UI placement: Panes appear alongside existing ERP views rather than replacing them. Pane Panes are context-aware. You specify which ERP view your pane appears in using the context field, and control whether it shows on child views with matchChildContext. 
{
	"capabilities": {
		"erp": {
			"pane": [
				{
					"title": "Customer Insights",
					"url": "https://your-app.example.com/pane/customers",
					"context": "$tenantSlug.customers",
					"matchChildContext": true
				}
			]
		}
	}
}
The context field uses a special syntax to refer to specific views in the ERP Cloud. The $tenantSlug refers to the current tenant, and the following text is the name of the view. For example, $tenantSlug.customers refers to the customers view in the current tenant’s ERP. Pane with customers as the specified context
Example: A sidebar panel that reacts to the merchant navigating between customers, displaying real-time analytics or notes for the currently selected customer.

​
Headless

A Headless app has no user interface. Your backend authenticates with JTL’s Identity Provider and calls the Cloud API directly. You can use it for backend-to-backend automation, such as syncing inventory with a warehouse system, pushing orders to a fulfillment provider, or running scheduled data transformations. Headless apps are similar to cron jobs or serverless functions that integrate with an external API. The merchant installs the app from the App Store, but there’s no iframe or AppBridge involved after setup. 
{
  "capabilities": {
    "erp": {
      "headless": {
        "url": "https://your-app.example.com/api/sync"
      }
    }
  }
}
Example: A nightly sync service that reads new orders from JTL and forwards them to a third-party fulfillment API, with no merchant interaction required after initial setup.

​
App Installation Flow

Merchants discover and install apps from the App Store. The installation process grants your app the permissions it needs to access the merchant’s data.
1

Browse and select

The merchant browses the App Store and selects an app.
2

Review and install

On the app’s detail page, the merchant reviews the description, screenshots, and required permissions, then clicks Install.
3

Permissions granted

The platform grants your app the scopes declared in your manifest. This happens automatically as part of the installation. The merchant does not need to approve individual scopes in a separate consent screen.
4

App active

The app is now active in the merchant’s environment. Depending on the integration type, it appears as a Hub card, ERP menu item, sidebar pane, or runs as a background service.

​
Authentication Flows

Every Cloud App gets an OAuth client with a ClientId and ClientSecret when registered in the Partner Portal. When a merchant installs your app, it receives access to that merchant’s tenant without the credentials changing. One set of credentials works across all tenants that install your app.

​
Machine-to-Machine (M2M)

Use this flow when your backend needs to call JTL Cloud APIs without any user interaction. Your backend authenticates directly with the Identity Provider using client credentials.
  1. Your backend sends its ClientId and ClientSecret to the Identity Provider.
  2. The Identity Provider validates the credentials and returns a JWT access token.
  3. Your backend uses the token (along with the X-Tenant-ID header) to call the JTL Cloud API.
  4. The API processes the request and returns the data.
This flow is ideal for headless apps, scheduled jobs, and any backend-to-backend communication.

​
Frontend-Initiated

Use this flow when your app has a frontend running in an iframe. The frontend gets a session token from the AppBridge, passes it to your backend, and the backend handles both session validation and API authentication.
1

Get session token

The frontend requests a session token from the AppBridge. This token contains the current user’s identity and tenant information.
2

Send to backend

The frontend sends its request to your backend, including the session token.
3

Authenticate and validate

Your backend does two things in parallel: requests an access token from the Identity Provider (client credentials), and validates the session token against JTL’s Account Service using JWKS.
4

Fetch and return

With a valid access token and confirmed tenant, your backend calls the JTL Cloud API and returns the response to the frontend.

​
What’s Next

App Shell & UI Integration

Learn how the AppBridge, iframe messaging, and Platform UI components work.

Authentication & Login

Implement OAuth 2.0 and session token flows in your app.

Using Platform APIs

Call the JTL Cloud and JTL-Wawi APIs from your backend with proper headers and scoping.