App Token Authentication

An app token identifies the merchant using your app and the tenant they belong to. It is a JWT issued by the platform identity provider, signed with RS256, and bound to your app. This means a token issued for another app cannot be used with yours. The way your app obtains the token depends on where it runs:

Where your app runs	How it obtains the token
Inside the Cloud ERP	`appBridge.method.call('getAppToken')`
On your own domain	Browser sign-in with `@jtl-software/cloud-apps-auth`. See Standalone Authentication.

Before You Start

Token verification requires two values. The CLI’s npm run register command writes these values to your backend .env file.

Variable	Value
`JTL_ISSUER`	The identity provider that issues app tokens, `https://id.jtl-cloud.com` in production
`JTL_APP_ID`	Your app’s ID, a GUID. Also shown in the Partner Portal under your app.

Understand the Token Claims

Once decoded, an app token contains claims that identify the token, the merchant, and the tenant:

{
  "aud": [
    "5aa3624f-2236-4e5b-b7e5-7091be7764f0"
  ],
  "client_id": "389707023228376722",
  "exp": 1788865347,
  "iat": 1788861747,
  "iss": "https://id.jtl-cloud.com",
  "jti": "V2_389845033982945061-at_389845033983010597",
  "nbf": 1788861747,
  "sub": "0292bace-2568-4722-a6fc-50023ca1650a",
  "urn:jtl:kundencenter_id": "1348883",
  "urn:jtl:tenant_id": "73bd3d84-f7e3-46c6-ba52-a870c76b9ee7"
}

Claim	Description
`aud`	Audience. Contains your app ID.
`client_id`	The OIDC client the token was issued to
`exp`	Expiry timestamp in Unix seconds. App tokens are valid for approximately one hour.
`iat`	Issue timestamp in Unix seconds
`iss`	The issuing identity provider
`jti`	Unique token identifier
`nbf`	Not-before timestamp in Unix seconds
`sub`	The signed-in merchant’s user ID
`urn:jtl:tenant_id`	The tenant the token is scoped to. Use this in the `X-Tenant-ID` header.
`urn:jtl:kundencenter_id`	The merchant’s JTL customer account number

The app token carries no profile claims. To read a merchant’s name or email, call the identity provider’s userinfo endpoint.

What Verification Checks

Verification is three separate checks. A token is valid only when all three pass.

Check	Passes when
Signature and issuer	The signature validates against the identity provider’s public keys, `iss` matches your issuer, and `exp` is present and in the future
Audience	`aud` contains your app ID
App ID	`urn:jtl:app_id` is absent, or equals your app ID

The public keys are published at ${JTL_ISSUER}/oauth/v2/keys. The token header carries a kid, and the key with the matching kid is the one that verifies it.

Reject the request when any check fails. A token that carries a valid signature but a different audience was minted for another app, and treating it as valid would let that app act through yours.

Verify the Token

Your frontend sends the token as Authorization: Bearer <token>. Your backend verifies it before acting on the request.

// The TypeScript SDK provides `verifyAppToken` to perfom the checks:
// lib/verify-app-token.ts
import { verifyAppToken } from '@jtl-software/cloud-apps-auth/verify';

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

export async function verify(authHeader: string) {
  const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : '';

  if (!token) {
    throw new Error('Missing Bearer app token');
  }

  const result = await verifyAppToken(token, { issuer: JTL_ISSUER, appId: APP_ID });

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

  return result.claims;
}

// VerifyAppToken.cs
  using Microsoft.Extensions.Configuration;
  using Microsoft.IdentityModel.JsonWebTokens;
  using Microsoft.IdentityModel.Protocols;
  using Microsoft.IdentityModel.Protocols.OpenIdConnect;
  using Microsoft.IdentityModel.Tokens;

  public static class VerifyAppToken
  {
      private static ConfigurationManager<OpenIdConnectConfiguration>? _configManager;

      // `configuration` is whatever you already have injected (FastEndpoints endpoints get it via
      // DI; from a minimal API handler, add `IConfiguration configuration` as a parameter).
      public static async Task<IDictionary<string, object>> VerifyAsync(
          string authHeader, IConfiguration configuration, CancellationToken ct = default)
      {
          var issuer = (configuration["JtlPlatform:Issuer"] ?? "https://id.jtl-cloud.com").TrimEnd('/');
          var appId = (configuration["JtlPlatform:AppId"] ?? "").Trim();

          var token = authHeader.StartsWith("Bearer ") ? authHeader[7..] : "";
          if (string.IsNullOrEmpty(token))
              throw new UnauthorizedAccessException("Missing Bearer app token");

          // Caches the IdP's published keys and refreshes them automatically (including retrying on
          // a signature failure), so a signing-key rotation on the IdP doesn't strand a long-running
          // process on a stale key set.
          _configManager ??= new ConfigurationManager<OpenIdConnectConfiguration>(
              $"{issuer}/.well-known/openid-configuration",
              new OpenIdConnectConfigurationRetriever(),
              new HttpDocumentRetriever());

          var config = await _configManager.GetConfigurationAsync(ct);
          var parameters = new TokenValidationParameters
          {
              ValidIssuer = issuer,
              IssuerSigningKeys = config.SigningKeys,
              ValidateIssuer = true,
              ValidateLifetime = true,
              RequireExpirationTime = true,
              // Audience is checked manually below, alongside urn:jtl:app_id, so a mismatch doesn't
              // get lost inside one opaque validation exception.
              ValidateAudience = false,
          };

          var result = await new JsonWebTokenHandler().ValidateTokenAsync(token, parameters);
          if (!result.IsValid)
              throw new UnauthorizedAccessException(result.Exception?.Message ?? "Invalid app token");
        var result = await new JsonWebTokenHandler().ValidateTokenAsync(token, parameters);
        if (!result.IsValid)
            throw new UnauthorizedAccessException(result.Exception?.Message ?? "Invalid app token");

        if (!ExtractAudience(result.Claims).Contains(appId))
            throw new UnauthorizedAccessException("Token audience does not contain this app");

        var hasAppIdClaim = result.Claims.TryGetValue("urn:jtl:app_id", out var appIdClaim);
        if (hasAppIdClaim && appIdClaim?.ToString() != appId)
            throw new UnauthorizedAccessException("Token was minted for a different app");

        return result.Claims;
    }

    private static IReadOnlyList<string> ExtractAudience(IDictionary<string, object> claims)
    {
        if (!claims.TryGetValue("aud", out var aud) || aud is null)
            return [];

        // `aud` can come back as a plain string or a list, depending on how many audiences the
        // token has.
        if (aud is IEnumerable<object> list)
            return list.Select(a => a.ToString() ?? "").ToList();

        return [aud.ToString() ?? ""];
    }
}

<?php
// src/Jtl/VerifyAppToken.php
declare(strict_types=1);

namespace App\Jtl;

use Firebase\JWT\JWK;
use Firebase\JWT\JWT;
use GuzzleHttp\Client;
use UnexpectedValueException;

final class VerifyAppToken
{
    private static ?Client $httpClient = null;

    public static function verify(string $authHeader): array
    {
        $issuer = rtrim(getenv('JTL_ISSUER') ?: 'https://id.jtl-cloud.com', '/');
        $appId = trim(getenv('JTL_APP_ID') ?: '');

        $token = str_starts_with($authHeader, 'Bearer ') ? substr($authHeader, 7) : '';

        if ($token === '') {
            throw new UnexpectedValueException('Missing Bearer app token');
        }

        // Fetched fresh each call rather than cached: a stale cache would silently break
        // verification the moment the IdP rotates its signing keys.
        $keys = JWK::parseKeySet(json_decode(
            (string) self::httpClient()->get("{$issuer}/oauth/v2/keys")->getBody(),
            true,
            flags: JSON_THROW_ON_ERROR
        ));

        $decoded = JWT::decode($token, $keys);
        $claims = json_decode((string) json_encode($decoded), true);

        if (($claims['iss'] ?? null) !== $issuer) {
            throw new UnexpectedValueException('Token issuer does not match');
        }

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

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

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

        return $claims;
    }

    private static function httpClient(): Client
    {
        return self::$httpClient ??= new Client();
    }
}

The TypeScript path uses verifyAppToken, which performs all checks and returns a per-check breakdown in result.checks rather than throwing, so you can report which check failed. The C# and PHP paths implement the same three checks directly.

Cache the key set rather than fetching it on every request. Public keys change infrequently, and the samples above hold the set for the process lifetime.

Use the Token to Identify the Tenant

After verifying the token, use the urn:jtl:tenant_id claim to identify the tenant associated with the request.

Fullstack Apps (Embedded Views)

If your app has a backend, the flow is:

Receive the app token from the frontend using the AppBridge.
Verify the token.
Read urn:jtl:tenant_id from the verified claims.
Obtain a service account token.
Call the JTL-Wawi via GraphQL using the service account token and the tenant ID.

// routes/graphql.ts
import express, { Request, Response } from 'express';
import { verify } from '../lib/verify-app-token';
import { getCachedAccessToken } from '../lib/token-cache';
 
const app = express();
 
app.post('/graphql', async (req: Request, res: Response) => {
    let tenantId: string;
 
    try {
        const claims = await verify(req.headers.authorization ?? '');
        const claim = claims?.['urn:jtl:tenant_id'];
 
        if (typeof claim !== 'string') {
            return res.status(400).json({ error: 'App token has no tenant claim' });
        }
 
        tenantId = claim;
    } catch (error) {
        return res.status(401).json({ error: 'Failed to verify app token' });
    }
 
    const accessToken = await getCachedAccessToken();
 
    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(req.body),
    });
 
    return res
        .status(response.status)
        .type('application/json')
        .send(await response.text());
});

// GraphqlEndpoint.cs
using System.IdentityModel.Tokens.Jwt;
using System.Net.Http.Headers;
 
public static class GraphqlEndpoint
{
    private static readonly HttpClient HttpClient = new();
 
    public static async Task<IResult> HandleAsync(HttpRequest request)
    {
        JwtSecurityToken jwt;
 
        try
        {
            jwt = await VerifyAppToken.VerifyAsync(request.Headers.Authorization.ToString());
        }
        catch (Exception)
        {
            return Results.Json(new { error = "Failed to verify app token" }, statusCode: 401);
        }
 
        var tenantId = jwt.Claims.FirstOrDefault(c => c.Type == "urn:jtl:tenant_id")?.Value;
 
        if (string.IsNullOrEmpty(tenantId))
            return Results.Json(new { error = "App token has no tenant claim" }, statusCode: 400);
 
        var accessToken = await TokenCache.GetCachedAccessTokenAsync();
 
        using var reader = new StreamReader(request.Body);
        var body = await reader.ReadToEndAsync();
 
        var upstream = new HttpRequestMessage(
            HttpMethod.Post,
            "https://api.jtl-cloud.com/erp/v2/graphql"
        );
        upstream.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
        upstream.Headers.Add("X-Tenant-ID", tenantId);
        upstream.Content = new StringContent(body, System.Text.Encoding.UTF8, "application/json");
 
        var response = await HttpClient.SendAsync(upstream);
 
        return Results.Content(
            await response.Content.ReadAsStringAsync(),
            "application/json",
            statusCode: (int)response.StatusCode
        );
    }
}

<?php
// src/Jtl/GraphqlController.php
declare(strict_types=1);
 
namespace App\Jtl;
 
use GuzzleHttp\Client;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Throwable;
 
final class GraphqlController
{
    private const GRAPHQL_ENDPOINT = 'https://api.jtl-cloud.com/erp/v2/graphql';
 
    public function __construct(private readonly Client $httpClient) {}
 
    public function __invoke(ServerRequestInterface $request, ResponseInterface $response): ResponseInterface
    {
        try {
            $claims = VerifyAppToken::verify($request->getHeaderLine('Authorization'));
        } catch (Throwable) {
            return self::json($response, ['error' => 'Failed to verify app token'], 401);
        }
 
        $tenantId = $claims['urn:jtl:tenant_id'] ?? null;
 
        if (!is_string($tenantId)) {
            return self::json($response, ['error' => 'App token has no tenant claim'], 400);
        }
 
        $accessToken = TokenCache::getCachedAccessToken();
 
        $upstream = $this->httpClient->post(self::GRAPHQL_ENDPOINT, [
            'headers' => [
                'Authorization' => "Bearer {$accessToken}",
                'X-Tenant-ID' => $tenantId,
                'Content-Type' => 'application/json',
            ],
            'body' => (string) $request->getBody(),
            'http_errors' => false,
        ]);
 
        $response->getBody()->write((string) $upstream->getBody());
 
        return $response
            ->withHeader('Content-Type', 'application/json')
            ->withStatus($upstream->getStatusCode());
    }
 
    private static function json(ResponseInterface $response, array $data, int $status = 200): ResponseInterface
    {
        $response->getBody()->write(json_encode($data, JSON_THROW_ON_ERROR));
        return $response->withHeader('Content-Type', 'application/json')->withStatus($status);
    }
}

The app token identifies the tenant. The service account token determines what the backend can do. The scopes declared in your manifest control the permissions available to the service account. See Service Account Authentication for obtaining and caching that token, and Scopes & Permissions for how the two tokens differ. If your app has no backend, it can call the API directly from the browser using the app token. In this case, the signed-in merchant’s own permissions apply. See Standalone Authentication for the implementation.

Tenant Mapping

Your backend should store a record that links the JTL tenant to your app’s internal state. Without this mapping, your backend cannot associate an incoming request with the merchant’s existing account or data. Use persistent storage rather than in-memory storage. In-memory data is lost when the server restarts and cannot be shared between multiple server instances.

What to Store

At minimum, persist the following the first time a merchant reaches your backend.

Field	Where it comes from	Why you need it
`tenantId`	The `urn:jtl:tenant_id` claim	Primary key, identifies the merchant
`installedAt`	Your server timestamp	Provides an audit trail and helps with debugging.
`installedByUserId`	The `sub` claim	Identifies the user who first connected the app.

If your app has its own user or account model, link the tenant ID to your internal record. A minimal PostgreSQL schema:

CREATE TABLE jtl_tenants (
  tenant_id      UUID PRIMARY KEY,
  installed_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  installed_by   UUID NOT NULL,
  updated_at     TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Writing the Record

Use an upsert rather than an insert. A merchant may connect your app more than once, and an existing tenant should update its record instead of causing a duplicate-key error.

import { Pool } from 'pg';
import { verify } from '../lib/verify-app-token';

const pool = new Pool();

app.post('/api/connect', async (req, res) => {
  try {
    const claims = await verify(req.headers.authorization ?? '');

    await pool.query(
      `INSERT INTO jtl_tenants (tenant_id, installed_by)
       VALUES ($1, $2)
       ON CONFLICT (tenant_id) DO UPDATE
           SET installed_by = EXCLUDED.installed_by,
               updated_at   = NOW()`,
      [claims?.['urn:jtl:tenant_id'], claims?.sub]
    );

    return res.json({ tenantId: claims?.['urn:jtl:tenant_id'] });
  } catch {
    return res.status(401).json({ error: 'Failed to verify app token' });
  }
});

using Npgsql;

public static class ConnectEndpoint
{
    private static readonly NpgsqlDataSource DataSource =
        NpgsqlDataSource.Create(Environment.GetEnvironmentVariable("DATABASE_URL")!);

    public static async Task<IResult> HandleAsync(HttpRequest request)
    {
        try
        {
            var jwt = await VerifyAppToken.VerifyAsync(request.Headers.Authorization.ToString());

            var tenantId = jwt.Claims.First(c => c.Type == "urn:jtl:tenant_id").Value;
            var userId = jwt.Claims.First(c => c.Type == "sub").Value;

            await using var cmd = DataSource.CreateCommand(
                """
                INSERT INTO jtl_tenants (tenant_id, installed_by)
                VALUES ($1, $2)
                ON CONFLICT (tenant_id) DO UPDATE
                    SET installed_by = EXCLUDED.installed_by,
                        updated_at   = NOW()
                """
            );
            cmd.Parameters.AddWithValue(Guid.Parse(tenantId));
            cmd.Parameters.AddWithValue(Guid.Parse(userId));
            await cmd.ExecuteNonQueryAsync();

            return Results.Json(new { tenantId });
        }
        catch (UnauthorizedAccessException)
        {
            return Results.Json(new { error = "Failed to verify app token" }, statusCode: 401);
        }
    }
}

<?php
// src/Jtl/ConnectController.php
declare(strict_types=1);

namespace App\Jtl;

use PDO;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Throwable;

final class ConnectController
{
    public function __construct(private readonly PDO $pdo) {}

    public function __invoke(ServerRequestInterface $request, ResponseInterface $response): ResponseInterface
    {
        try {
            $claims = VerifyAppToken::verify($request->getHeaderLine('Authorization'));
        } catch (Throwable) {
            return self::json($response, ['error' => 'Failed to verify app token'], 401);
        }

        $stmt = $this->pdo->prepare(
            'INSERT INTO jtl_tenants (tenant_id, installed_by)
             VALUES (:tenant_id, :installed_by)
             ON CONFLICT (tenant_id) DO UPDATE
                 SET installed_by = EXCLUDED.installed_by,
                     updated_at   = NOW()'
        );

        $stmt->execute([
            ':tenant_id' => $claims['urn:jtl:tenant_id'],
            ':installed_by' => $claims['sub'],
        ]);

        return self::json($response, ['tenantId' => $claims['urn:jtl:tenant_id']]);
    }

    private static function json(ResponseInterface $response, array $data, int $status = 200): ResponseInterface
    {
        $response->getBody()->write(json_encode($data, JSON_THROW_ON_ERROR));
        return $response->withHeader('Content-Type', 'application/json')->withStatus($status);
    }
}

Reading the Record

On each incoming request, verify the token, take the tenant ID from its claims, and look up your record:

const claims = await verify(req.headers.authorization ?? '');

const result = await pool.query(
  'SELECT * FROM jtl_tenants WHERE tenant_id = $1',
  [claims?.['urn:jtl:tenant_id']]
);

if (result.rowCount === 0) {
  return res.status(404).json({ error: 'Tenant not found' });
}

const tenant = result.rows[0];

What Not to Do

A few patterns cause most tenant-mapping bugs in production.

Don’t	Why
Store tenant mappings only in memory	Wiped on every restart, does not survive multiple instances
Trust a tenant ID sent in a request body, URL, or header	A client can send any value. Take it from the verified token’s claims.
Store the app token itself	App tokens expire within the hour. Store the tenant ID they prove, not the token.
Assume tenant IDs are sequential or predictable	They are UUIDs. Treat them as opaque identifiers.

Token Lifetime

App tokens are valid for approximately one hour. Request a fresh token rather than holding one across a long-running session.

const { accessToken } = await appBridge.method.call<{ accessToken: string }>(
  'getAppToken'
);

Calling getAppToken before each backend request keeps the token current without requiring your app to handle token expiry itself.

Common Errors

The failures you are most likely to hit, and what causes them.

Verification fails on the audience check

The aud claim does not contain your app ID. JTL_APP_ID is the GUID shown in the Partner Portal under your app. Compare the value in your .env against the one in the portal.

Verification fails on signature or issuer

The token was issued by a different environment than the one your backend is verifying against. Confirm JTL_ISSUER matches the environment your app is registered in.

Verification fails on a token that worked earlier

The token has expired. App tokens are valid for approximately one hour, so a token captured during debugging stops verifying. Request a fresh one with getAppToken.

API calls return 403 after successful verification

The token verified, so the merchant and tenant are known, but the call exceeded what the calling credential is permitted to do. A backend calling with a service account is bound by the scopes declared in your manifest. See Scopes & Permissions.

What’s Next?

Service Account Authentication

Obtain and cache the access token your backend uses to call the JTL Cloud API.

Using Platform APIs

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

Standalone Authentication

Sign merchants in from an app running on your own domain.

Scopes & Permissions

Control what your app can access, and how enforcement differs by token.

Essentials

Cloud Apps

ERP Integration

Before You Start

Understand the Token Claims

What Verification Checks

Verify the Token

Use the Token to Identify the Tenant

Fullstack Apps (Embedded Views)

Tenant Mapping

What to Store

Writing the Record

Reading the Record

What Not to Do

Token Lifetime

Common Errors

What’s Next?

Service Account Authentication

Using Platform APIs

Standalone Authentication

Scopes & Permissions

​Before You Start

​Understand the Token Claims

​What Verification Checks

​Verify the Token

​Use the Token to Identify the Tenant

​Fullstack Apps (Embedded Views)

​Standalone Frontend Apps: Browser Sign-in

​Tenant Mapping

​What to Store

​Writing the Record

​Reading the Record

​What Not to Do

​Token Lifetime

​Common Errors

​What’s Next?

Service Account Authentication

Using Platform APIs

Standalone Authentication

Scopes & Permissions

Before You Start

Understand the Token Claims

What Verification Checks

Verify the Token

Use the Token to Identify the Tenant

Fullstack Apps (Embedded Views)

Standalone Frontend Apps: Browser Sign-in

Tenant Mapping

What to Store

Writing the Record

Reading the Record

What Not to Do

Token Lifetime

Common Errors

What’s Next?