PHP

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

Build the Slim 4 backend for a JTL Cloud App using PHP 8 and firebase/php-jwt 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: PHP 8.1+, Slim 4, Guzzle for HTTP requests, vlucas/phpdotenv for environment variables, firebase/php-jwt for JWT verification.

Prerequisites

You need:

• ✅ A finished frontend from the Build the Frontend page, running locally on http://localhost:5173
• ✅ PHP 8.1 or higher. Run php --version to check.
• ✅ Composer for dependency management. Run composer --version to check.

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 initialise a Composer project inside it.

cd my-jtl-app
mkdir backend
cd backend
composer init --name="my-jtl-app/backend" --type=project --no-interaction

Your project structure now looks like this:

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

2. Install Packages

composer require slim/slim slim/psr7 guzzlehttp/guzzle vlucas/phpdotenv firebase/php-jwt

Package	Purpose
slim/slim	The Slim 4 micro-framework: routing, request and response handling
slim/psr7	The PSR-7 implementation Slim uses by default
guzzlehttp/guzzle	HTTP client for making requests to JTL APIs
vlucas/phpdotenv	Loads environment variables from a .env file
firebase/php-jwt	Parses the JWKS and verifies app token signatures

3. Set up Environment Variables

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. 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.

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

vendor
.env

4. 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/JtlAuth.php:

<?php

declare(strict_types=1);

namespace App;

use GuzzleHttp\ClientInterface;

class JtlAuth
{
    private const AUTH_ENDPOINT = 'https://id.jtl-cloud.com/oauth/v2/token';
    public const API_BASE_URL = 'https://api.jtl-cloud.com';
    private const TOKEN_SCOPE = 'openid';

    private ?string $cachedToken = null;
    private int $tokenExpiresAt = 0;

    public function __construct(
        private readonly string $clientId,
        private readonly string $clientSecret,
        private readonly ClientInterface $httpClient,
    ) {
    }

    public function getJwt(): string
    {
        if ($this->cachedToken !== null && time() < $this->tokenExpiresAt) {
            return $this->cachedToken;
        }

        if (empty($this->clientId) || empty($this->clientSecret)) {
            throw new \RuntimeException('CLIENT_ID and CLIENT_SECRET must be defined in .env');
        }

        $authString = base64_encode("{$this->clientId}:{$this->clientSecret}");

        $response = $this->httpClient->request('POST', self::AUTH_ENDPOINT, [
            'http_errors' => false,
            'headers' => [
                'Content-Type' => 'application/x-www-form-urlencoded',
                'Accept' => 'application/json',
                'Authorization' => "Basic {$authString}",
            ],
            'form_params' => [
                'grant_type' => 'client_credentials',
                'scope' => self::TOKEN_SCOPE,
            ],
        ]);

        $statusCode = $response->getStatusCode();
        $body = $response->getBody()->getContents();

        if ($statusCode < 200 || $statusCode >= 300) {
            throw new \RuntimeException("Failed to fetch JWT ({$statusCode}): {$body}");
        }

        $data = json_decode($body, true);
        $expiresIn = $data['expires_in'] ?? 3599;
        $this->cachedToken = $data['access_token'];
        $this->tokenExpiresAt = time() + $expiresIn - 30;

        return $this->cachedToken;
    }
}

The credentials are Base64-encoded and sent as a client_credentials grant to JTL’s auth endpoint. The access token is cached in memory until 30 seconds before expiry, so repeat calls within the same request reuse it.

5. Build the Token Verifier

The backend verifies the app token before trusting anything in it. firebase/php-jwt parses the identity provider’s key set and selects the key matching the token’s kid.

Create backend/src/AppTokenVerifier.php:

<?php

declare(strict_types=1);

namespace App;

use Firebase\JWT\JWK;
use Firebase\JWT\JWT;
use GuzzleHttp\ClientInterface;

class AppTokenVerifier
{
    private ?array $keys = null;

    public function __construct(
        private readonly string $issuer,
        private readonly string $appId,
        private readonly ClientInterface $httpClient,
    ) {
    }

    public function verify(string $token): array
    {
        $claims = (array) JWT::decode($token, $this->getKeys());

        if (($claims['iss'] ?? null) !== $this->issuer) {
            throw new \RuntimeException('Token issuer does not match.');
        }

        if (!isset($claims['exp'])) {
            throw new \RuntimeException('Token has no expiry.');
        }

        $audience = (array) ($claims['aud'] ?? []);
        if (!in_array($this->appId, $audience, true)) {
            throw new \RuntimeException('Token audience does not contain this app.');
        }

        $appIdClaim = $claims['urn:jtl:app_id'] ?? null;
        if ($appIdClaim !== null && $appIdClaim !== $this->appId) {
            throw new \RuntimeException('Token was minted for a different app.');
        }

        return $claims;
    }

    private function getKeys(): array
    {
        if ($this->keys !== null) {
            return $this->keys;
        }

        $response = $this->httpClient->request('GET', "{$this->issuer}/oauth/v2/keys", [
            'http_errors' => false,
            'headers' => ['Accept' => 'application/json'],
        ]);

        $statusCode = $response->getStatusCode();

        if ($statusCode < 200 || $statusCode >= 300) {
            throw new \RuntimeException("Failed to fetch JWKS ({$statusCode})");
        }

        $jwks = json_decode($response->getBody()->getContents(), true);

        return $this->keys = JWK::parseKeySet($jwks);
    }
}

JWT::decode verifies the signature against the key whose kid matches the token header, and checks the expiry. The issuer and audience checks are separate because the library does not enforce them.

The urn:jtl:app_id claim is optional. When absent the token is valid for your app, and when present it must equal your app ID.

The key set is fetched on first use and held on the instance, so repeat verifications within the same request do not refetch. For cross-request reuse, swap the in-memory cache for APCu or another shared cache.

6. Build the Connect Tenant Endpoint

Now connect the verifier into a Slim route. The frontend’s shell layout sends the app token to the backend as a Bearer token.

Create backend/public/index.php:

<?php

use App\JtlAuth;
use App\AppTokenVerifier;
use Dotenv\Dotenv;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;
use GuzzleHttp\Client;

require __DIR__ . '/../vendor/autoload.php';

Dotenv::createImmutable(__DIR__ . '/..')->load();

$httpClient = new Client();
$auth = new JtlAuth($_ENV['CLIENT_ID'] ?? '', $_ENV['CLIENT_SECRET'] ?? '', $httpClient);
$verifier = new AppTokenVerifier(
    rtrim($_ENV['JTL_ISSUER'] ?? 'https://id.jtl-cloud.com', '/'),
    trim($_ENV['JTL_APP_ID'] ?? ''),
    $httpClient,
);

$app = AppFactory::create();
$app->addBodyParsingMiddleware();

// Allow the Vite dev server to call the API during development
$app->add(function (Request $request, $handler) {
    $response = $handler->handle($request);
    return $response
        ->withHeader('Access-Control-Allow-Origin', 'http://localhost:5173')
        ->withHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type')
        ->withHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
});

$app->options('/{routes:.+}', fn(Request $req, Response $res) => $res);

$app->get('/api/connect-tenant', function (Request $request, Response $response) use ($verifier) {
    $authHeader = $request->getHeaderLine('Authorization');
    $token = str_starts_with($authHeader, 'Bearer ') ? substr($authHeader, 7) : '';

    if ($token === '') {
        $response->getBody()->write(json_encode(['error' => 'App token is required']));
        return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
    }

    try {
        $claims = $verifier->verify($token);
        $tenantId = $claims['urn:jtl:tenant_id'] ?? null;

        if (!is_string($tenantId)) {
            $response->getBody()->write(json_encode(['error' => 'App token has no tenant claim']));
            return $response->withStatus(400)->withHeader('Content-Type', 'application/json');
        }

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

        $response->getBody()->write(json_encode([
            'success' => true,
            'tenantId' => $tenantId,
            'clientId' => $claims['client_id'] ?? null,
        ]));
        return $response->withHeader('Content-Type', 'application/json');
    } catch (\Throwable $e) {
        $response->getBody()->write(json_encode(['error' => 'Failed to verify app token']));
        return $response->withStatus(401)->withHeader('Content-Type', 'application/json');
    }
});

$app->run();

The bootstrap loads .env, instantiates JtlAuth with the credentials and AppTokenVerifier with the issuer and app ID. Both instances are then captured by the route closure via use ($verifier) and shared across requests.

The CORS middleware allows 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 headers are a useful safety net during development.

See Tenant Mapping for more on managing tenants in production.

7. Configure Composer Autoloading

Open backend/composer.json and add a psr-4 autoload mapping for the App\ namespace:

{
    "name": "my-jtl-app/backend",
    "type": "project",
    "require": {
        "slim/slim": "^4.15",
        "slim/psr7": "^1.7",
        "guzzlehttp/guzzle": "^7.9",
        "vlucas/phpdotenv": "^5.6",
        "firebase/php-jwt": "^6.10"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Then regenerate the autoloader so Composer picks up the new mapping:

composer dump-autoload

This tells Composer that any class in the App\ namespace lives under the src/ directory, which is how JtlAuth and SessionVerifier get loaded when index.php references them.

8. Run the Backend

Start the dev server:

php -S localhost:5273 -t public

You should see:

PHP 8.x.x Development Server (http://localhost:5273) started

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"}. That’s the expected outcome for an invalid token. A real app token from the App Shell will follow the same path and succeed.

Common Issues

'Class App\JtlAuth not found' or similar autoload error

This error means Composer’s autoloader doesn’t know where to find the class. The most common cause is forgetting to regenerate the autoload files after adding the psr-4 mapping to composer.json.

Running composer dump-autoload from the backend/ directory rebuilds vendor/autoload.php to include any new namespace mappings. The error should clear after the next request.

'CLIENT_ID and CLIENT_SECRET must be defined in .env'

This error means the backend started but couldn’t find your credentials in the environment. The most common cause is that .env is sitting in the wrong directory, or that the Dotenv::createImmutable() call is pointing at the wrong path.

'Failed to verify app token' with real credentials

Verification checks the signature, issuer, expiry, and audience. 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 valid for about an hour, so a token captured earlier during debugging will fail on expiry.

'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

A CORS error usually means the request reached the backend but the browser blocked the response because the origin didn’t match what the backend allows. The CORS middleware in index.php is configured to allow http://localhost:5173, which matches the default Vite dev server port.

If the Vite dev server is running on a different port (for example, because port 5173 was already in use and Vite picked 5174 instead), the browser will see a mismatch. Updating the Access-Control-Allow-Origin value in index.php to match the actual Vite port, or freeing up port 5173, should resolve it.

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.