App Manifest

The technical manifest that registers your app: identity, lifecycle, authentication, and capabilities.

The app manifest is a JSON document that registers your app with JTL. It declares the app’s identity, the URL JTL loads during setup, the OAuth flows its credentials can use, and the capabilities through which your app integrates with the platform.

You register your app by pasting this manifest into the JSON Code Editor in the Partner Portal under Manage apps. You can also register an app using the registration wizard form directly.

Top-level Fields

Two fields identify the app and its release.

Property	Type	Required	Description
technicalName	string	Yes	Stable internal identifier for the app. Max 100 characters. Used as a fallback display name.
version	string	Yes	App release version. Strict semver, digits only (e.g. 1.0.0). Pre-release tags are not allowed.

Lifecycle

The lifecycle object defines the URL JTL loads when a merchant installs your app.

Property	Type	Required	Description
lifecycle.configurationUrl	string	No	URL rendered in an iframe during setup. Use it to present setup UI, complete the AppBridge handshake, and persist the tenant connection.

The URL must be a standard http:// or https:// URL.

The manifest validator accepts {metadata.*} placeholders in this URL, but JTL does not substitute them at runtime. Use a static URL, and encode any app identity you need directly in the path or query string.

Identifying the App

If you publish multiple apps, each one needs its own configurationUrl. Two apps sharing the same URL cause the wrong setup UI to render when a merchant installs either one.

Give each app a distinct URL, either with a separate route:

"lifecycle": {
  "configurationUrl": "https://example.com/setup/inventory-sync"
}

Or by encoding the app’s identity in the query string:

"lifecycle": {
  "configurationUrl": "https://example.com/setup?app=inventory-sync"
}

Use separate routes if you control routing and want cleaner URLs. Use query parameters if you prefer a single handler that switches behavior based on the app.

A working configuration flow is included when you create an app with the CLI, npm create @jtl-software/cloud-app@latest.

Authentication

The authentication object declares the OAuth flows your app’s credentials can use. It is optional, and each entry is independent. An app that declares neither entry keeps the credentials it already has.

Property	Type	Required	Description
authentication.publicClient	object	No	Browser sign-in client, for apps that authenticate users themselves
authentication.serviceAccount	object	No	Machine credential, for calls your backend makes as itself

The CLI writes this object based on the frontend and backend options you select when creating the app. Selecting a frontend adds publicClient. Selecting a backend adds serviceAccount.

For the app shapes these combinations produce, see Architecture Overview.

Public Client

An authorization code client with PKCE and no secret, used to sign users in against the platform identity provider.

Property	Type	Required	Description
redirectUris	array of string	Required if loopbackPorts is absent	URLs where a browser-based app receives the authorization code. Matched exactly, so placeholders and wildcards are rejected.
loopbackPorts	array of integer	Required if redirectUris is absent	Ports between 1 and 65535 for a command line or desktop tool that receives the callback on the user’s own machine
loopbackCallbackPath	string	No	Path appended to each loopback port. Must begin with /. Defaults to /callback. Ignored without loopbackPorts.
postLogoutRedirectUris	array of string	No	URLs the browser returns to after sign-out. Without an entry, sign-out ends on the platform identity provider.

An app with a hosted interface declares its callback URLs:

"authentication": {
  "publicClient": {
    "redirectUris": ["https://example.com/callback"],
    "postLogoutRedirectUris": ["https://example.com/"]
  }
}

A command line or desktop tool declares loopback ports instead:

"authentication": {
  "publicClient": {
    "loopbackPorts": [51789, 51790],
    "loopbackCallbackPath": "/callback"
  }
}

Each loopback port is registered twice, as http://127.0.0.1:{port}{path} and as http://localhost:{port}{path}, so either spelling resolves.

Declaring both redirectUris and loopbackPorts is valid, and applies to an app that ships a hosted interface alongside a command line tool.

Service Account

A machine user for the client_credentials grant, used for calls your backend makes as itself rather than on behalf of a signed-in user.

Property	Type	Required	Description
clientCredentials	boolean	Yes	Set to true to request the service account
onBehalfOfUser	boolean	No	Set to true to also let the service account act as one of your signed-in users, so calls run with that user’s permissions and tenant. Requires clientCredentials.
description	string	No	Free text describing what the service account is used for. Between 1 and 500 characters.

"authentication": {
  "serviceAccount": {
    "clientCredentials": true,
    "onBehalfOfUser": true,
    "description": "Nightly inventory sync worker"
  }
}

Credentials at Registration

Client IDs and secrets are issued when you register the app, and npm run register writes them to your .env file.

Two constraints apply.

• Changing the authentication object after registration does not add or reconcile credentials. An app registered without serviceAccount does not gain one by declaring it later.
• There is no secret rotation path.

Capabilities

Capabilities define where and how your app integrates with JTL. Each key under capabilities maps to a surface. See Architecture Overview for a description of each integration type.

Hub

Controls how the app appears in the JTL Hub dashboard. When a merchant clicks the app’s card, the platform redirects to this URL.

Property	Type	Required	Description
capabilities.hub.appLauncher.redirectUrl	string	Required if hub is present	URL the platform redirects to when the app card is clicked in the Hub

Without a redirectUrl, the app card has no destination.

ERP Menu Items

Add entries to the Cloud ERP sidebar under the App section. Each menu item links to a page in your app, loaded inside the ERP iframe.

Property	Type	Required	Description
id	string	Yes	Stable internal identifier for the menu item
name	string	Yes	Display name shown in the navigation
url	string	Yes	URL loaded when the item is clicked

ERP API Scopes

Declare the JTL-Wawi API resources your app intends to use. Declared scopes are validated against the allowed list at registration.

Property	Type	Required	Description
capabilities.erp.api.scopes	array of string	No	API permission scopes the app requests

Scope values come from a fixed list, and any value outside it is rejected at registration. A subset for reference:

"scopes": [
  "items.read", "items.write",
  "orders.read", "orders.write",
  "customers.read", "customers.write"
]

Declared scopes are enforced at the API layer on JTL-Wawi 2.2.0 and higher. See Scopes & Permissions for the full list and for how enforcement differs between access and app tokens.

ERP Panel

Add a sidebar panel that appears alongside an ERP view. Panels are declared as entries in the capabilities.erp.pane array. They are context-aware and show only on matching pages. When more than one installed app targets the same view, each app renders as a tab within the panel, and tabs beyond the panel width collapse into an overflow menu.

Property	Type	Required	Description
id	string	No	Internal identifier for the panel
context	string	Yes	View the panel appears on, written as the ERP route path (e.g. customers). See Panel Contexts for the available values.
url	string	Yes	URL loaded inside the panel iframe
requiredScopes	array of string	No	Per-panel scope override, using the same scope values as capabilities.erp.api.scopes

Panel Contexts

A context targets a Cloud ERP view by its route path. For example, the customers view route is /customers and customers can be used as the context.

These are the top-level views a panel can target:

Context	View
customers	Customers
items	Items
salesorders	Sales orders
salesquotations	Sales quotations
salesinvoices	Sales invoices

A panel also stays visible on the descendant routes of its context. Declaring customers shows the panel on the customer list and on a specific customer’s detail view. Matching is on full path segments, so customers covers customers and customers.<id> but not an unrelated view.

For reading the current entity in a panel, see Reading Panel Context.

Complete Example

A manifest as the CLI generates it with a frontend and a backend selected, declaring a Hub redirect, one ERP menu item, three API scopes, and one panel on the customers view:

{
  "version": "1.0.0",
  "technicalName": "my-example-app",
  "lifecycle": {
    "configurationUrl": "https://example.com/configure"
  },
  "authentication": {
    "publicClient": {
      "redirectUris": ["https://example.com/callback"],
      "postLogoutRedirectUris": ["https://example.com/"]
    },
    "serviceAccount": {
      "clientCredentials": true,
      "description": "Reads orders and items from the JTL API"
    }
  },
  "capabilities": {
    "hub": {
      "appLauncher": {
        "redirectUrl": "https://example.com/hub/launch"
      }
    },
    "erp": {
      "menuItems": [
        {
          "id": "menu-item-1",
          "name": "Mein Menüpunkt",
          "url": "https://example.com/erp/menu"
        }
      ],
      "api": {
        "scopes": ["orders.read", "orders.write", "items.read"]
      },
      "pane": [
        {
          "id": "panel-1",
          "context": "customers",
          "url": "https://example.com/erp/pane/customers",
          "requiredScopes": ["customers.read"]
        }
      ]
    }
  }
}

What’s Next?

Listing Manifest

Define how your app appears in the App Store or is shared privately.

App Shell & UI

Communicate with the host using AppBridge, and build UI with Platform UI components.