Node.js - JTL Developer Documentation

Build the Express backend for a JTL Cloud App using Node.js, TypeScript, and the jose library for JWT verification. By the end, the backend runs locally and the frontend’s “Waiting for backend” placeholder turns into a real connection. Stack: Node.js 24.16.0+, Express, TypeScript, jose for JWT 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 session token from your frontend is valid and was issued by JTL. To do this:

Your backend authenticates with JTL using its client credentials
Fetches JTL’s public keys (JWKS)
And uses them to verify the session token’s signature

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.

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
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`	Verifies JWTs using JTL’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 two secrets: a client ID and a client secret, both issued by JTL when you create your app. 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
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. This token has two uses: fetching the public keys for session token verification, and making tenant-scoped calls to the JTL Cloud API. Create backend/src/jtl-auth.ts:

const AUTH_ENDPOINT = 'https://auth.jtl-cloud.com/oauth2/token';
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 response = await fetch(AUTH_ENDPOINT, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/x-www-form-urlencoded',
			Authorization: `Basic ${authString}`,
		},
		body: new URLSearchParams({ grant_type: 'client_credentials' }),
	});

	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 token is short-lived, so the function fetches a fresh one on each call. For higher-traffic backends you’d add caching.

6. Build the Session Verifier

With an access token in hand, the backend can fetch the public keys it needs to verify session tokens. The jose library handles the cryptographic work once it has the public key in the right format. Create backend/src/verify-session.ts:

import { importJWK, jwtVerify } from 'jose';
import { getJwt, getApiBaseUrl } from './jtl-auth.js';

export interface SessionTokenPayload {
	exp: number;
	userId: string;
	tenantId: string;
	tenantSlug: string;
}

export async function verifySessionToken(
	sessionToken: string,
): Promise<SessionTokenPayload> {
	const accessToken = await getJwt();
	const baseUrl = getApiBaseUrl();

	const response = await fetch(`${baseUrl}/account/.well-known/jwks.json`, {
		headers: { Authorization: `Bearer ${accessToken}` },
	});

	if (!response.ok) {
		throw new Error(`Failed to fetch JWKS (${response.status})`);
	}

	const jwks = await response.json();
	
	// Select the signing key by its JWK properties (use=sig, alg=EdDSA)
	const signingKey = jwks.keys.find(
		(k: { use?: string; alg?: string }) =>
			k.use === 'sig' && k.alg === 'EdDSA',
	);
 
	if (!signingKey) {
		throw new Error('No EdDSA signing key found in JWKS');
	}
 
	const publicKey = await importJWK(signingKey, 'EdDSA');

	const { payload } = await jwtVerify(sessionToken, publicKey);
	return payload as unknown as SessionTokenPayload;
}

The function fetches the JWKS document from the JTL API, imports the first key as an EdDSA public key, and asks jose to verify the session token’s signature against it. If the signature is valid and the token isn’t expired, jwtVerify returns the decoded payload. If anything is wrong, it throws an error.

7. Build the Connect Tenant Endpoint

Now connect the verifier into an Express route. The frontend’s shell layout sends the session token to /api/connect-tenant and expects a tenant ID back. Create backend/src/server.ts:

import express, { type Request, type Response } from 'express';
import cors from 'cors';
import { verifySessionToken } from './verify-session.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 sessionToken = req.headers['x-session-id'] as string;

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

    try {
        const payload = await verifySessionToken(sessionToken);

        // In a production app, you'd store the tenant connection in your database here
        console.log('Tenant connected:', payload.tenantId);

        return res.json({
            success: true,
            tenantId: payload.tenantId,
            userId: payload.userId,
            tenantSlug: payload.tenantSlug,
        });
    } catch (error) {
        console.error('Connection failed:', error);
        return res
            .status(401)
            .json({ error: 'Failed to verify session 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 the Tenant Mapping section 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 session token to confirm the route is reachable:

curl http://localhost:5273/api/connect-tenant \
  -H "x-Session-id: fake-token"

You should get back a 401 response with {"error":"Failed to verify session token"}. A real session 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.

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 session 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:

​Prerequisites

​What you’re Building

​1. Set up the Project

​2. Install Packages

​3. Configure TypeScript

​4. Set up Environment Variables

​5. Build the Auth Helper

​6. Build the Session Verifier

​7. Build the Connect Tenant Endpoint

​8. Add Run Scripts

​9. Run the Backend

​Common Issues

​Next: Connect and Fetch Data

Connect and Fetch Data