Standalone Authentication

Sign merchants in from an app running on your own domain, and call the JTL Cloud API on their behalf.

An app that runs on your own domain signs merchants in itself, against the platform identity provider. It receives an access token, an ID token, and a refresh token, and uses the access token to call the JTL Cloud API.

This is the browser sign-in flow described in Architecture Overview. Apps that render inside the Hub or Cloud ERP receive the same token through AppBridge instead. See App Token Authentication for that flow.

An app with no frontend or fullstack authenticates as itself with a service account. See Service Account Authentication for that flow.

Access Requires an Installation

Signing in with a JTL ID proves who the user is; it does not by itself grant access to your app. Access follows the installation: a user can access your app’s data only for an organization where your app is installed.

When a user signs in, they select the organization they are acting for. That organization is included in the token’s urn:jtl:tenant_id.

If the organization has installed your app, the token includes the scopes granted to your app in urn:jtl:api_scopes. If it has not, the token does not include your app’s scopes, and API calls against that organization return 403 Forbidden.

A merchant, or one of their staff, must therefore install your app for their organization from the App Store before anyone in that organization can use it. See Scopes & Permissions for how installation grants and bounds your scopes.

Adding Sign-In to your App

To get started, install the JTL’s auth library:

npm install @jtl-software/cloud-apps-auth

Create the Manifest and Register your App

You must register your app with JTL before it can access JTL resources.

Create an app.json file in your frontend project root:

{
	"version": "1.0.0",
	"technicalName": "standalone-app",
	"lifecycle": {},
	"authentication": {
		"publicClient": {
			"redirectUris": ["https://standalone-app.example.com/callback"],
			"postLogoutRedirectUris": ["https://standalone-app.example.com/"]
		}
	},
	"capabilities": {
		"hub": {
			"appLauncher": {}
		},
		"erp": {}
	}
}

The publicClient object tells JTL this is a browser-based authentication flow, where the user signs in through the JTL identity provider and is redirected back to your app after authentication.

redirectUris defines the allowed URLs where JTL can send the user after signing in. postLogoutRedirectUris defines where the user can be redirected after signing out. See App Manifest: Authentication for the full field list.

Next, create a .env file in your frontend project root:

VITE_JTL_ISSUER=.... # the JTL identity provider
VITE_JTL_CLIENT_ID=.... # the public client ID for your app

The registration command reads your app.json and .env configuration and uses them to register the app with JTL.

Run:

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

You can also use the registration wizard on Partner Portal to register your app.

Configure the Environment

Once your app is registered, copy the public client ID in the Partner Portal and add it to your environment variables:

.env

VITE_JTL_ISSUER=.... # the JTL identity provider
VITE_JTL_CLIENT_ID=.... # the public client ID for your app

If you’re using the CLI to register the app, it will automatically populate your .env file with the required values.

Wrap your App

The provider holds the session and makes it available to the rest of your component tree. Mount it above your router, passing the values from your environment.

main.tsx

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { JtlAuthProvider } from '@jtl-software/cloud-apps-auth';
import App from './App';

createRoot(document.getElementById('root')!).render(
	<StrictMode>
		<JtlAuthProvider
			issuer={import.meta.env.VITE_JTL_ISSUER}
			clientId={import.meta.env.VITE_JTL_CLIENT_ID}
		>
			<App />
		</JtlAuthProvider>
	</StrictMode>,
);

Until your app is registered and clientId has a value, the provider renders its children unchanged.

Protect a Route

RequireJtlAuth renders its children only when a merchant is signed in. Anyone reaching a protected route without a session is sent to the identity provider and returned to the same route afterwards.

App.tsx

import { RequireJtlAuth } from '@jtl-software/cloud-apps-auth';
import DashboardPage from './pages/DashboardPage';

const App: React.FC = () => (
	<RequireJtlAuth>
		<DashboardPage />
	</RequireJtlAuth>
);

export default App;

Above the gated content, RequireJtlAuth renders a top bar showing the signed-in merchant and a sign-out control. To place that bar yourself, use the JtlAuthBar component directly.

Gate the routes that run on your own domain. Routes that render inside the Hub or Cloud ERP receive identity through AppBridge and are not gated this way.

Read the Signed-In User

useJtlAuth returns the current session. The profile object carries the ID token claims, and access_token is the credential you send to the JTL Cloud API.

import { useJtlAuth } from '@jtl-software/cloud-apps-auth';

const DashboardPage: React.FC = () => {
	const { user } = useJtlAuth();

	if (!user) return null;

	const { profile } = user;
	const accessToken = user.access_token;

	return (
		<div>
			<h1>{profile.name ?? profile.email}</h1>
		</div>
	);
};

Inside RequireJtlAuth a session always exists, so the null check guards only the moment before the provider resolves.

Fetch the User Profile

The ID token carries basic identity claims. The provider’s userinfo endpoint returns the full set, including the tenant the merchant belongs to.

import { useEffect, useState } from 'react';
import { fetchUserInfo, useJtlAuth } from '@jtl-software/cloud-apps-auth';

const issuer = import.meta.env.VITE_JTL_ISSUER ?? '';

const useJtlUserInfo = () => {
	const { user } = useJtlAuth();
	const accessToken = user?.access_token;

	const [userInfo, setUserInfo] = useState<Record<string, unknown> | null>(
		null,
	);
	const [error, setError] = useState<string | null>(null);

	useEffect(() => {
		if (!accessToken || !issuer) return;
		let cancelled = false;

		setUserInfo(null);
		setError(null);

		fetchUserInfo(issuer, accessToken)
			.then((info) => !cancelled && setUserInfo(info))
			.catch(
				(err) =>
					!cancelled &&
					setError(err instanceof Error ? err.message : String(err)),
			);

		return () => {
			cancelled = true;
		};
	}, [accessToken]);

	return { userInfo, error };
};

The response contains the standard OpenID Connect claims alongside JTL-specific ones:

{
	"sub": "8f14e45f-ceea-4c2b-9b1e-3a7d2f6b0c11",
	"email": "[e-mail]",
	"email_verified": true,
	"name": "Alex Beispiel",
	"given_name": "Alex",
	"family_name": "Beispiel",
	"preferred_username": "[e-mail]",
	"locale": null,
	"updated_at": 1787157038,
	"urn:jtl:tenant_id": "3c9a1d70-52b8-4f6e-8d21-b4e7f09a5c33",
	"urn:jtl:kundencenter_id": "1000000"
}

Claim	Type	Description
sub	string (UUID)	Stable identifier for the merchant across sessions
email	string	Merchant’s email address
email_verified	boolean	Whether the address has been confirmed
name	string	Full display name
given_name	string	First name
family_name	string	Last name
preferred_username	string	Username the merchant signs in with
locale	string or null	Preferred locale, when set
updated_at	integer	Unix timestamp of the last profile change
urn:jtl:tenant_id	string (UUID)	Tenant the merchant belongs to. Required for JTL Cloud API calls.
urn:jtl:kundencenter_id	string	Merchant’s JTL customer account number

Call the JTL-Wawi API

API calls carry the access token and the tenant the merchant belongs to. Read the tenant from urn:jtl:tenant_id in the userinfo response.

const fetchItems = async (accessToken: string, tenantId: string) => {
	const response = await fetch('https://api.jtl-cloud.com/erp/v2/graphql', {
		method: 'POST',
		headers: {
			Authorization: `Bearer ${accessToken}`,
			'X-Tenant-ID': tenantId,
			'Content-Type': 'application/json',
		},
		body: JSON.stringify({
			query: `
        query Items($first: Int!) {
          items(first: $first) {
            nodes {
              id
              name
            }
          }
        }
      `,
			variables: { first: 20 },
		}),
	});

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

	return response.json();
};

The library refreshes the access token as it approaches expiry, so read user.access_token at call time rather than holding a copy in component state.

Optionally, you can use the getTokenInformation function to get the token information.

import { getTokenInformation } from '@jtl-software/cloud-apps-auth';

const info = await getTokenInformation(token);
// info?.userId, info?.organizationId, info?.expiresAt
// info?.username, info?.name, info?.email

The organizationId in the token information is the same as the tenantId.

Sign Out

RequireJtlAuth includes a sign-out control in its top bar. To sign out from elsewhere in your app, call signoutRedirect from the session hook.

import { useJtlAuth } from '@jtl-software/cloud-apps-auth';
import { Button } from '@jtl-software/platform-ui-react';

const SignOutButton: React.FC = () => {
	const { signoutRedirect } = useJtlAuth();

	return (
		<Button
			label='Sign out'
			variant='default'
			onClick={() => signoutRedirect()}
		/>
	);
};

Sign-out clears the local session and redirects to the identity provider, which returns the merchant to one of the URLs declared in postLogoutRedirectUris. Without an entry, sign-out ends on the identity provider rather than back in your app.

Common Issues

Common failures and what causes them.

Sign-in fails with a redirect URI error

The identity provider matches redirect URIs exactly, so the URL your app sends must be present in your manifest character for character. A trailing slash, a different port, or http where the manifest declares https all count as a mismatch. Check the value in your manifest against the URL in the browser address bar when the error appears, and register a new app version if they differ.

The merchant returns to the sign-in page repeatedly

This happens when the session cannot be stored, usually because the app is served over http on a host other than localhost, or because browser storage is blocked. Serve the app over https in any environment other than local development, and confirm that third-party storage restrictions are not applying to your domain.

The userinfo request returns 401

The access token has expired or was rejected. Read user.access_token at the point of the call rather than capturing it once, so the value reflects the most recent refresh. If the token is current and the request still fails, confirm that VITE_JTL_ISSUER points at the same environment your app is registered in.

A protected route shows a configuration hint instead of signing in

The client ID is missing, so the library has nothing to authenticate against. Confirm that VITE_JTL_CLIENT_ID is set and that the provider receives it. A freshly scaffolded app has no client ID until it is registered, so run npm run register first.

The sign-in top bar renders without styling

Tailwind has not scanned the library’s dist directory, so its utility classes were never generated. Add the @source directive for @jtl-software/cloud-apps-auth/dist to your CSS alongside the one for Platform UI, then restart the dev server.

API calls return a tenant error

The X-Tenant-ID header is missing or does not match a tenant the merchant belongs to. Read the value from urn:jtl:tenant_id in the userinfo response.

The merchant signs in but every API call returns 403

Sign-in succeeds, but the organization the merchant selected has not installed your app, so the token carries none of your scopes. Check urn:jtl:api_scopes in the token: if it is empty or missing your scopes, ask the merchant to install your app for that organization from the App Store, or to switch to an organization that already has it. See Access Requires an Installation.

What’s Next?

Using Platform APIs

Query the JTL Cloud and JTL-Wawi APIs with the right headers and scoping.

App Manifest

Declare the public client, redirect URIs, and capabilities your app needs.

Architecture Overview

Compare the integration types and authentication flows available to your app.

Platform UI

Build your interface with the JTL component library.