Architecture Overview

Understand how JTL Cloud Apps are structured, how they communicate with the platform, and the four integration types available.

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 three integration types. Each type determines where your app appears, how it communicates, and what kind of experience it provides.

Type	UI	Communication	Use case
Hub-Link	Card in JTL Hub	Redirect to your URL	Entry points, external tools, dashboards
ERP-iFrame	Embedded in ERP main content	AppBridge messages	Rich interactive UI within the ERP
Pane	Sidebar in ERP	AppBridge messages	Context-aware panels (e.g., customer detail sidebar)

All three types require a manifest.json and app registration through the Partner Portal.

Hub-Link

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.

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.

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.

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.

Example: A sidebar panel that reacts to the merchant navigating between customers, displaying real-time analytics or notes for the currently selected customer.

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, or sidebar pane.

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.

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.