Node.js

Build the Express backend for your JTL Cloud App. Verify app tokens, fetch access tokens, and proxy requests to the JTL Cloud API.

Build the Express backend for a JTL Cloud App using Node.js, TypeScript, and the JTL auth library for app token verification. By the end, the backend runs locally and the frontend’s “Connecting to JTL Platform…” placeholder turns into a real connection.

Stack: Node.js 24.16.0+, Express, TypeScript, @jtl-software/cloud-apps-auth for app token verification.

Prerequisites

You need:

• ✅ A finished frontend from the Build the Frontend page, running locally on http://localhost:5173
• ✅ Node.js v24.16.0 or higher (current LTS, includes npm). Verify with node --version and npm --version

What you’re Building

During setup, your backend verifies that the app token from your frontend is valid and was issued by JTL for your app.

To do this:

• Your backend fetches the identity provider’s public keys (JWKS)
• Verifies the token’s signature, issuer, and expiry against them
• Confirms the token’s audience is your app, so a token minted for another app is rejected

Once verified, the token tells your backend which tenant (merchant) and user is using your app. Your backend can then make tenant-scoped requests to the JTL Cloud API on their behalf, authenticating with its own client credentials.

1. Set up the Project

Create a backend folder alongside the existing frontend folder, then initialize it.

cd my-jtl-app
mkdir backend
cd backend
npm init -y

Your project structure now looks like this:

my-jtl-app/
├── frontend/      # From the previous page
└── backend/       # New

2. Install Packages

npm install express cors jose @jtl-software/cloud-apps-auth
npm install -D typescript tsx @types/node @types/express @types/cors

Package	Purpose
express	HTTP server and routing
cors	Allows the frontend dev server to call the backend during development
jose	JSON Web Token (JWT) operations, used by @jtl-software/cloud-apps-auth
@jtl-software/cloud-apps-auth	Verifies app tokens against the identity provider’s public keys
typescript	Type checking and tsc compiler
tsx	Runs TypeScript files directly during development without a build step
@types/*	Type definitions for the runtime packages

3. Configure TypeScript

Create backend/tsconfig.json:

{
	"compilerOptions": {
		"target": "ES2022",
		"module": "NodeNext",
		"moduleResolution": "NodeNext",
		"esModuleInterop": true,
		"strict": true,
		"skipLibCheck": true,
		"outDir": "dist",
		"rootDir": "src"
	},
	"include": ["src/**/*"]
}

This configuration uses Node’s native ESM support (NodeNext) with strict type checking. The outDir and rootDir settings keep compiled output separate from source files when you eventually build for production.

4. Set up Environment Variables

The backend needs four values. CLIENT_ID and CLIENT_SECRET are the credentials JTL issues when you create your app. JTL_APP_ID is your app’s ID, which an app token’s audience must contain. JTL_ISSUER is the identity provider that issues app tokens. You will get the real values from the Partner Portal in the next page. For now, create the file with placeholder values so the rest of the setup works.

Create backend/.env:

CLIENT_ID=your-client-id-here
CLIENT_SECRET=your-client-secret-here
JTL_APP_ID=your-app-id-here
JTL_ISSUER=https://id.jtl-cloud.com
PORT=5273

The frontend’s Vite dev proxy is already configured to forward /api/* requests to localhost:5273, so the PORT value matches that target.

Add .env to backend/.gitignore so the secrets don’t end up in version control:

node_modules
dist
.env

5. Build the Auth Helper

The first piece of the backend is a function that authenticates with JTL using your client credentials and returns an access token. Your backend uses it to make tenant-scoped calls to the JTL Cloud API.

Create backend/src/jtl-auth.ts:

const JTL_ISSUER = (process.env.JTL_ISSUER ?? 'https://id.jtl-cloud.com').replace(
    /\/$/,
    '',
);
const AUTH_ENDPOINT = `${JTL_ISSUER}/oauth/v2/token`;
const TOKEN_SCOPE = 'openid';
const API_BASE_URL = 'https://api.jtl-cloud.com';

export function getApiBaseUrl(): string {
    return API_BASE_URL;
}

export async function getJwt(): Promise<string> {
    const clientId = process.env.CLIENT_ID;
    const clientSecret = process.env.CLIENT_SECRET;

    if (!clientId || !clientSecret) {
        throw new Error('CLIENT_ID and CLIENT_SECRET must be defined in .env');
    }

    const authString = Buffer.from(`${clientId}:${clientSecret}`).toString(
        'base64',
    );

    const body = new URLSearchParams({ grant_type: 'client_credentials' });
    body.set('scope', TOKEN_SCOPE);

    const response = await fetch(AUTH_ENDPOINT, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            Authorization: `Basic ${authString}`,
        },
        body,
    });

    const data = await response.json();

    if (!response.ok) {
        throw new Error(
            `Failed to fetch JWT (${response.status}): ${data.error}`,
        );
    }

    return data.access_token;
}

This encodes the client credentials as Base64, sends a client_credentials grant request to JTL’s auth endpoint, and returns the resulting access token. The function fetches a fresh one on each call. For higher-traffic backends you’d add caching. See Service Account Authentication.

6. Build the Token Verifier

The backend verifies the app token before trusting anything in it. verifyAppToken fetches the identity provider’s public keys, checks the signature, issuer, and expiry, then confirms the token was minted for your app.

Create backend/src/verify-app-token.ts:

import { verifyAppToken } from '@jtl-software/cloud-apps-auth/verify';
import type { JWTPayload } from 'jose';

const ISSUER = (process.env.JTL_ISSUER ?? 'https://id.jtl-cloud.com').replace(
	/\/$/,
	'',
);
const APP_ID = (process.env.JTL_APP_ID ?? '').trim();

export async function verify(token: string): Promise<JWTPayload> {
	const result = await verifyAppToken(token, {
		issuer: ISSUER,
		appId: APP_ID,
	});

	if (!result.valid) {
		throw new Error(
			`App token verification failed: ${JSON.stringify(result.checks)}`,
		);
	}

	return result.claims!;
}

verifyAppToken runs three checks and returns a breakdown rather than throwing, so you can report which one failed:

Check	Passes when
signatureAndIssuer	The signature validates against the identity provider’s keys, iss matches, and exp is present and in the future
audience	aud contains your app ID
appId	urn:jtl:app_id is absent, or equals your app ID

result.valid is true only when all three pass. The key set is fetched on first use and cached, so repeated verifications do not hit the network.

7. Build the Connect Tenant Endpoint

Now connect the verifier into an Express route. The frontend’s shell layout sends the app token to the backend as a Bearer token and expects a claim with the tenant information including tenant ID, client ID, etc.

Create backend/src/server.ts:

import express, { type Request, type Response } from 'express';
import cors from 'cors';
import { verify } from './verify-app-token.js';

const app = express();
const port = Number(process.env.PORT) || 5273;

app.use(cors({ origin: 'http://localhost:5173' }));
app.use(express.json());

app.get('/api/connect-tenant', async (req: Request, res: Response) => {
    const authHeader = req.headers.authorization ?? '';
    const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : '';

    if (!token) {
        return res.status(400).json({ error: 'App token is required' });
    }

    try {
        const claims = await verify(token);
        const tenantId = claims['urn:jtl:tenant_id'];

        if (typeof tenantId !== 'string') {
            return res.status(400).json({ error: 'App token has no tenant claim' });
        }

        // In a production app, you'd store the tenant connection in your database here

        return res.json({
            success: true,
            tenantId,
            clientId: claims.client_id,
        });
    } catch {
        return res.status(401).json({ error: 'Failed to verify app token' });
    }
});

app.listen(port, () => {
    console.log(`Backend listening on http://localhost:${port}`);
});

CORS is configured to allow requests from the Vite dev server on port 5173. The dev proxy in vite.config.ts already routes frontend fetch('/api/...') calls to this backend, but the CORS middleware is a useful safety net during development and stays out of the way in production.

See Tenant Mapping for more on managing tenants in production.

8. Add Run Scripts

Open backend/package.json and replace the scripts block:

"scripts": {
    "dev": "tsx watch --env-file=.env src/server.ts",
    "build": "tsc",
    "start": "node --env-file=.env dist/server.js"
}

The dev script uses tsx watch to run TypeScript directly, restarting the server when any source file changes. The --env-file=.env flag loads environment variables natively without needing dotenv. The build and start scripts compile to JavaScript and run the compiled output for production.

Also update the "type": "commonjs" to "type": "module" below the scripts in the package.json file so that Node can treat .js files as ES modules.

9. Run the Backend

Start the dev server:

npm run dev

You should see:

Backend listening on http://localhost:5273

In a second terminal, send a request with a fake app token to confirm the route is reachable:

curl http://localhost:5273/api/connect-tenant \
  -H "Authorization: Bearer fake-token"

You should get back a 401 response with {"error":"Failed to verify app token"}. A real app token from the App Shell will follow the same path and succeed.

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.

'Failed to verify app token' with real credentials

Verification checks four things, and the audience check is the one most often wrong. JTL_APP_ID is the app ID shown in the Partner Portal under your app, not the client ID.

If the audience is correct, confirm JTL_ISSUER matches the environment your app is registered in. A token issued by one environment does not verify against another’s keys.

App tokens are also valid for about an hour, so a token captured earlier during debugging will fail.

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.

Next: Connect and Fetch Data

The backend verifies app tokens and is ready to call the JTL Cloud API. The remaining work is registering your app with JTL to get real credentials, installing the app in the JTL Hub, and pulling product data from JTL-Wawi:

Connect and Fetch Data

Register your app, install it in the JTL Hub, and fetch products from JTL-Wawi.