Connect and Fetch Data

Bring everything together. Register your app with JTL to get real credentials, install it in the JTL Hub, then add an items endpoint to your backend and a product table to your frontend.

Prerequisites

You need:

✅ A finished frontend from the Build the Frontend guide
✅ A finished backend from either the Node.js, C#, or PHP guide
✅ A JTL ID (your login to the JTL ecosystem)
✅ Access to an organization (tenant) in the Partner Portal (created automatically on first login if you don’t have one yet)
✅ JTL-Wawi installed and running locally, with at least one product, and connected to JTL Cloud.

If you don’t have JTL Cloud set up yet, follow the step-by-step guide: Create a Developer Account.

What you’re Building

So far, the frontend and backend are only loosely connected. The frontend can render the app, and the backend can verify authentication tokens, but neither side is yet tied to a real merchant installation. This guide closes the loop. By the end, opening the app from the ERP Cloud menu will show a table of real products from JTL-Wawi.

1. Create the Manifest

Your app’s manifest declares how it integrates with JTL: the URLs it exposes and its ERP Cloud menu items. Create an app.json file in the project root:

{
  "version": "1.0.0",
  "technicalName": "my-jtl-app",
  "lifecycle": {
    "configurationUrl": "http://localhost:5173/setup"
  },
  "capabilities": {
    "hub": {
      "appLauncher": {
        "redirectUrl": "http://localhost:5173/hub"
      }
    },
    "erp": {
	  "api": {
			"scopes": ["items.read"]
		},	
      "menuItems": [
        {
          "id": "my-jtl-app-menu",
          "name": "My JTL App",
          "url": "http://localhost:5173/erp"
        }
      ]
    }
  }
}

Three of the URLs map directly to the three frontend routes you built:

Manifest field	Page in your code
`lifecycle.configurationUrl`	`_shell.setup.tsx`
`capabilities.hub.appLauncher.redirectUrl`	`hub.tsx`
`capabilities.erp.menuItems[].url`	`_shell.erp.tsx`

For the full field reference, see the App Manifest.

The example uses http://localhost:5173/.... When you deploy, replace these with your production domain. All URLs must be publicly reachable. localhost works only because the JTL App Shell runs in your browser, not on JTL’s servers.

2. Register your App

CLI
Registration Wizard

With your manifest saved as app.json in your project root, run the CLI:

npx -y @jtl-software/create-cloud-app@latest register

The CLI signs you in with your JTL ID, lets you select a tenant, and registers the app from your app.json. It then writes your client ID and client secret to a .env file in your project.

In the Partner Portal, open Manage apps and click Create to open the app creation wizard. It walks through four steps: Basics, The integration, API permissions, and Summary.

Already have your app.json? Select JSON Code Editor, paste it, and save. The form populates with your values, and you continue from the Summary step to review and create the app.

Basics

Enter the Internal app name used to identify the app (it is not shown to customers) and the App-Version in major.minor.patch format, for example 1.0.0. Click Continue.

The integration

Enter the URLs that connect your app to JTL:

Configuration URL: the setup entry point JTL calls when a merchant installs your app. Use http://localhost:5173/setup, which maps to your _shell.setup.tsx route.
App-Card-URL: the URL opened from the app card in JTL Hub after setup completes. Use http://localhost:5173/hub, which maps to your hub.tsx route.

Under Possible integration into JTL ERP Cloud, select Add menu item and add one item pointing to http://localhost:5173/erp, which maps to your _shell.erp.tsx route. This is the entry the merchant clicks in the ERP sidebar to open your app.Click Continue.

API permissions

Select the API permissions your app needs. For this guide, the app reads product data, so the items read scope is sufficient. Use the search field to find and select it, then click Continue.

Your selection is recorded with your app, though the API doesn’t enforce it yet. Declare the scopes your app actually uses so it behaves correctly once enforcement is live.

Summary

Review the configuration. Each section has an edit control if you need to change a value. When everything is correct, create the app.

Copy your credentials

After the app is created, you’ll see your Client ID and Client Secret.

The Client Secret is shown only once. Copy the value immediately. If you lose it, you’ll need to register a new app.

Don’t commit your environment files. They contain your client secrets. The CLI writes them to paths that the template’s .gitignore already excludes, but verify this before pushing to a shared repository.

3. Update your Backend Credentials

Replace the placeholder values you set earlier with the real Client ID and Client Secret.

Node.js
C#
PHP

Open backend/.env and replace the placeholder values:

CLIENT_ID=your-actual-client-id
CLIENT_SECRET=your-actual-client-secret
PORT=5273

The tsx watch command picks up source file changes automatically, but environment variables are read once at startup. Stop and restart the backend to pick up the new values.

From the Backend/ directory, update the user-secrets values:

dotnet user-secrets set "Jtl:ClientId" "your-actual-client-id"
dotnet user-secrets set "Jtl:ClientSecret" "your-actual-client-secret"

ASP.NET Core reads configuration once at startup. Stop and restart the backend to pick up the new values.

Open backend/.env and replace the placeholder values:

CLIENT_ID=your-actual-client-id
CLIENT_SECRET=your-actual-client-secret
PORT=5273

PHP’s built-in development server reads environment variables once at startup. Stop the server with Ctrl+C and start it again to pick up the new values:

4. Run Both Processes

You need both the frontend and backend running. Open two terminals from the project root. Terminal 1 (backend):

Node.js
C#
PHP

cd backend
npm run dev

cd Backend
dotnet run

cd backend
php -S localhost:5273 -t public

Terminal 2 (frontend):

cd frontend
npm run dev

Opening http://localhost:5173 directly in a browser will show a blank page or the placeholder error state. The app is meant to be rendered inside the JTL App Shell, which is what the next step covers.

5. Install the App in JTL Hub

Open JTL Hub

Go to JTL Hub and log in.

Find your App

Navigate to the Manage apps menu and click the Apps in development tab. You should see your newly registered app.

Install the App

Once the app is installed, you’ll see a success screen with the option to configure the app. Click the Configure app button to proceed to the next step.

Complete the Setup

Click the Complete Setup button on your setup page. This triggers the full setup handshake between your app and JTL.

The setup page now displays a valid tenant ID. This confirms that the session token was successfully verified through your backend and that the App Shell recognizes the installation as complete.

6. Add an Items Endpoint

The backend can now make tenant-scoped calls to the JTL Cloud API. The next step is adding an endpoint that fetches products from JTL-Wawi via GraphQL.

Every API request that needs to access tenant data needs an X-Tenant-ID header. The backend extracts this value from the verified session token payload. See the Session Token Payload reference for details.

Node.js
C#
PHP

Add the items route to backend/src/server.ts. Place it alongside the existing connect-tenant route:

import { getJwt } from './jtl-auth.js';

app.get('/api/items', async (req: Request, res: Response) => {
	const authHeader = req.header('authorization');
	if (!authHeader?.startsWith('Bearer ')) {
		return res
			.status(401)
			.json({ error: 'Missing or invalid Authorization header' });
	}

	const sessionToken = authHeader.slice(7);

	try {
		const payload = await verifySessionToken(sessionToken);
		const accessToken = await getJwt();

		const response = await fetch(
			'https://api.jtl-cloud.com/erp/v2/graphql',
			{
				method: 'POST',
				headers: {
					'Content-Type': 'application/json',
					Authorization: `Bearer ${accessToken}`,
					'X-Tenant-ID': payload.tenantId,
				},
				body: JSON.stringify({
					operationName: 'GetERPItems',
					query: `
          query GetERPItems {
            QueryItems(first: 10) {
              nodes { id sku name notes basePriceUnit }
              totalCount
            }
          }
        `,
				}),
			},
		);

		const body = await response.json();
		return res.json(body);
	} catch (error) {
		console.error('Failed to fetch items:', error);
		return res.status(500).json({ error: 'Failed to fetch items' });
	}
});

The route reads the session token from the Authorization header (sent by the frontend as a Bearer token), verifies it to extract the tenant ID, fetches a fresh access token, and forwards the GraphQL response back to the frontend as-is.

Create Backend/Controllers/ItemsController.cs:

using System.Net.Http.Headers;
using System.Text;
using Backend.Services;
using Microsoft.AspNetCore.Mvc;

namespace Backend.Controllers;

[ApiController]
[Route("api/items")]
public class ItemsController : ControllerBase
{
    private readonly HttpClient _http;
    private readonly JtlAuthService _auth;
    private readonly SessionVerifier _verifier;

    public ItemsController(
        IHttpClientFactory httpFactory,
        JtlAuthService auth,
        SessionVerifier verifier)
    {
        _http = httpFactory.CreateClient();
        _auth = auth;
        _verifier = verifier;
    }

    [HttpGet]
    public async Task<IActionResult> Get()
    {
        var authHeader = Request.Headers.Authorization.ToString();
        if (string.IsNullOrEmpty(authHeader) || !authHeader.StartsWith("Bearer "))
        {
            return Unauthorized(new { error = "Missing or invalid Authorization header" });
        }

        var sessionToken = authHeader.Substring("Bearer ".Length);

        try
        {
            var payload = await _verifier.VerifyAsync(sessionToken);
            var accessToken = await _auth.GetJwtAsync();

            var query = """
            {
              "operationName": "GetERPItems",
              "query": "query GetERPItems { QueryItems(first: 10) { nodes { id sku name notes basePriceUnit } totalCount } }"
            }
            """;

            var request = new HttpRequestMessage(
                HttpMethod.Post,
                $"{_auth.ApiBaseUrl}/erp/v2/graphql");
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            request.Headers.Add("X-Tenant-ID", payload.TenantId);
            request.Content = new StringContent(query, Encoding.UTF8, "application/json");

            var response = await _http.SendAsync(request);
            var body = await response.Content.ReadAsStringAsync();

            return Content(body, "application/json");
        }
        catch (Exception ex)
        {
            return StatusCode(500, new { error = "Failed to fetch items", details = ex.Message });
        }
    }
}

The controller reads the session token from the Authorization header (sent by the frontend as a Bearer token), verifies it to extract the tenant ID, fetches a fresh access token, and forwards the GraphQL response back to the frontend as-is.The existing app.MapControllers() call in Program.cs already discovers this controller, so no extra registration is needed.

Add the items route to backend/public/index.php. Place it alongside the existing connect-tenant route:

$app->get('/api/items', function (Request $request, Response $response) use ($auth, $verifier, $httpClient) {
    $authHeader = $request->getHeaderLine('Authorization');
    if (!str_starts_with($authHeader, 'Bearer ')) {
        $response->getBody()->write(json_encode(['error' => 'Missing or invalid Authorization header']));
        return $response->withStatus(401)->withHeader('Content-Type', 'application/json');
    }

    $sessionToken = substr($authHeader, 7);

    try {
        $payload = $verifier->verify($sessionToken);
        $accessToken = $auth->getJwt();

        $apiResponse = $httpClient->request('POST', JtlAuth::API_BASE_URL . '/erp/v2/graphql', [
            'http_errors' => false,
            'headers' => [
                'Content-Type' => 'application/json',
                'Accept' => 'application/json',
                'Authorization' => "Bearer {$accessToken}",
                'X-Tenant-ID' => $payload['tenantId'],
            ],
            'json' => [
                'operationName' => 'GetERPItems',
                'query' => 'query GetERPItems { QueryItems(first: 10) { nodes { id sku name notes basePriceUnit } totalCount } }',
            ],
        ]);

        $body = $apiResponse->getBody()->getContents();

        $response->getBody()->write($body);
        return $response->withHeader('Content-Type', 'application/json');
    } catch (\Throwable $e) {
        error_log("Failed to fetch items: {$e->getMessage()}");
        $response->getBody()->write(json_encode(['error' => 'Failed to fetch items']));
        return $response->withStatus(500)->withHeader('Content-Type', 'application/json');
    }
});

7. Display Items in the ERP Page

Replace frontend/src/routes/_shell.erp.tsx with a version that fetches and renders the products:

import { createFileRoute } from '@tanstack/react-router';
import { Box, Text } from '@jtl-software/platform-ui-react';
import { useCallback, useEffect, useState } from 'react';
import { useAppBridge } from '../appBridge';

interface Item {
	id: string;
	sku: string;
	name: string;
}

interface ItemsResponse {
	data: {
		QueryItems: {
			nodes: Item[];
			totalCount: number;
		};
	};
}

function ErpPage() {
	const { appBridge, tenantId } = useAppBridge();
	const [items, setItems] = useState<Item[]>([]);
	const [totalCount, setTotalCount] = useState(0);
	const [loading, setLoading] = useState(false);
	const [error, setError] = useState<string | null>(null);

	const fetchItems = useCallback(async () => {
		if (!appBridge) return;
		try {
			setLoading(true);
			const sessionToken =
				await appBridge.method.call<string>('getSessionToken');

			const res = await fetch('/api/items', {
				headers: { Authorization: `Bearer ${sessionToken}` },
			});

			if (!res.ok) {
				throw new Error(`Request failed (${res.status})`);
			}

			const data: ItemsResponse = await res.json();
			setItems(data.data.QueryItems.nodes || []);
			setTotalCount(data.data.QueryItems.totalCount || 0);
		} catch (err) {
			console.error(String(err));
			setError(
				err instanceof Error ? err.message : 'Failed to load products',
			);
		} finally {
			setLoading(false);
		}
	}, [appBridge]);

	useEffect(() => {
		fetchItems();
	}, [fetchItems]);

	if (error) {
		return (
			<Box className='p-8'>
				<Text type='h2' weight='bold' color='danger' as='h1'>
					Error
				</Text>
				<Box className='mt-2'>
					<Text type='body' color='muted'>
						{error}
					</Text>
				</Box>
			</Box>
		);
	}

	return (
		<Box className='p-8'>
			<Box className='mb-4'>
				<Text type='h2' weight='bold' as='h1'>
					My JTL Cloud App
				</Text>
			</Box>
			<Box className='mb-6'>
				<Text type='body' color='muted'>
					Connected to tenant:{' '}
					<code className='bg-gray-100 px-2 py-1 rounded'>
						{tenantId}
					</code>
				</Text>
			</Box>

			<Box className='mb-3'>
				<Text type='h3' weight='semibold' as='h2'>
					Products from Cloud-ERP
				</Text>
			</Box>

			{loading ? (
				<Text type='body' color='muted'>
					Loading products...
				</Text>
			) : items.length === 0 ? (
				<Text type='body' color='muted'>
					No products found. Make sure your test account has items in
					Cloud-ERP.
				</Text>
			) : (
				<>
					<Box className='mb-3'>
						<Text type='small' color='muted'>
							Showing {items.length} of {totalCount} products
						</Text>
					</Box>
					<table className='w-full text-left border-collapse'>
						<thead>
							<tr className='border-b border-gray-200'>
								<th className='py-5 pr-8 font-semibold'>sku</th>
								<th className='py-5 pr-8 font-semibold'>
									name
								</th>
							</tr>
						</thead>
						<tbody>
							{items.map((item) => (
								<tr
									key={item.id}
									className='border-b border-gray-200'
								>
									<td className='py-2 text-sm pr-8'>
										{item.sku}
									</td>
									<td className='py-2 text-sm pr-8'>
										{item.name}
									</td>
								</tr>
							))}
						</tbody>
					</table>
				</>
			)}
		</Box>
	);
}

export const Route = createFileRoute('/_shell/erp')({
	component: ErpPage,
});

On mount, the component requests a session token from the AppBridge, sends it to your backend as the Authorization header, and renders the returned products in a table. The session token round-trip means the backend always knows which tenant the request belongs to, even though the frontend only ever holds a short-lived signed token. A sample response from the GraphQL API looks like this:

{
	"data": {
		"QueryItems": {
			"nodes": [
				{
					"id": "895d2d4d-4ed4-44c7-ac61-ebec01000000",
					"sku": "AR2016041-VKO",
					"name": "Men's T-shirt"
				},
				{
					"id": "895d2d4d-4ed4-44c7-ac61-ebec06000000",
					"sku": "AR2016041-002",
					"name": "Men's T-shirt orange S"
				}
			],
			"totalCount": 674
		}
	}
}

In the ERP Cloud, navigate to the App menu and find the My JTL App menu item that the manifest registered. Clicking it loads /erp inside the App Shell. You should see a header reading My JTL Cloud App, the connected tenant ID, and a table listing the first ten products from your JTL-Wawi instance. This completes the full handshake flow: the App Shell loads your frontend in an iframe, AppBridge provides a short-lived session token, your backend verifies the token and uses its access token to make a tenant-scoped request to the JTL Cloud API, and the response is returned to the browser.

Common Issues

'Cannot find module ./jtl-auth.js' or similar import error

This error usually means TypeScript and Node are resolving modules differently.With "type": "module" in package.json and "module": "NodeNext" in tsconfig.json, Node expects ES module imports to include file extensions. Even if your source file is jtl-auth.ts, the import must use ./jtl-auth.js.TypeScript resolves this correctly during development, and Node finds the compiled .js file at runtime.If you prefer not to use .js extensions, switch to "module": "CommonJS" in tsconfig.json and remove "type": "module" from package.json.

'CLIENT_ID and CLIENT_SECRET must be defined in .env'

This means the backend started without loading your environment variables.The most common cause is running Node without the --env-file=.env flag. In that case, the .env file exists but is never read.The dev and start scripts already include this flag. If you’re running the server manually, add it back or use npm run dev.Also confirm that the .env file is inside the backend/ directory. The path is resolved relative to where Node is executed.

'Failed to fetch JWT (401)' from the auth endpoint

A 401 from the auth endpoint means the credentials are not valid.If you are still using placeholder values, this is expected. Real credentials are provided after registering your app in the Partner Portal.If you have already registered:

check for typos or extra spaces in .env
restart the dev server after making changes

Environment variables are only read at startup, so updates to .env require a restart.

The frontend can reach the backend but still shows 'Waiting for backend'

This usually means the backend responded, but not with a successful (2xx) response.The frontend treats any non-2xx response as an error and shows the placeholder state.Open the browser console and inspect the /api/connect-tenant response:

a 401 is expected at this stage without real credentials
a 500 or network error indicates a backend issue (check server logs)

Once valid credentials are configured, this state resolves automatically.

CORS error in the browser console

This means the browser blocked the response due to an origin mismatch.The backend allows requests from http://localhost:5173, which is the default Vite dev server port. If Vite runs on a different port (for example, 5174), the request will be rejected.Update the origin in server.ts to match the actual port, or restart Vite on 5173.If you’re using the Vite dev proxy for /api/*, CORS should not appear. Seeing this error usually means the request is being made directly to the backend instead of going through the proxy.

What’s Next?

You’ve built a working JTL Cloud App from scratch: a frontend that runs inside the JTL App Shell, a backend that verifies session tokens and proxies requests to the JTL Cloud API, and a real connection to a tenant pulling live product data. Where to go from here:

Test your App

Validate your app in the sandbox with test data.

Using Platform APIs

Use the JTL-Wawi REST and GraphQL APIs, handle responses, and work with tenant-scoped data.

GraphQL Playground

Try queries and mutations interactively against your ERP instance.

App Shell & UI

Learn how to integrate deeper with the JTL UI and App Shell.

Submit your App

Publish to the App Store, or share your app privately with activation codes.

Get Started

Prerequisites

What you’re Building

1. Create the Manifest

2. Register your App

3. Update your Backend Credentials

4. Run Both Processes

5. Install the App in JTL Hub

6. Add an Items Endpoint

7. Display Items in the ERP Page

8. Open the App from the ERP Menu

Common Issues

What’s Next?

Test your App

Using Platform APIs

GraphQL Playground

App Shell & UI

Submit your App

​Prerequisites

​What you’re Building

​1. Create the Manifest

​2. Register your App

​3. Update your Backend Credentials

​4. Run Both Processes

​5. Install the App in JTL Hub

​6. Add an Items Endpoint

​7. Display Items in the ERP Page

​8. Open the App from the ERP Menu

​Common Issues

​What’s Next?

Test your App

Using Platform APIs

GraphQL Playground

App Shell & UI

Submit your App

Prerequisites

What you’re Building

1. Create the Manifest

2. Register your App

3. Update your Backend Credentials

4. Run Both Processes

5. Install the App in JTL Hub

6. Add an Items Endpoint

7. Display Items in the ERP Page

8. Open the App from the ERP Menu

Common Issues

What’s Next?