Service Account Authentication

A service account allows your backend to authenticate as your app without a merchant being signed in. It uses the OAuth 2.0 client credentials grant to obtain a access token. Use a service account when your backend needs to make API calls on its own, such as:

Processing webhooks
Running scheduled jobs
Calling the API on behalf of a merchant after verifying their app token

The permissions available to the service account are controlled by the scopes declared in your app manifest.

Before You Start

Your backend needs the credentials issued when you registered your app.

Variable	Value
`CLIENT_ID`	Client ID from the Partner Portal under your app’s Service Account section
`CLIENT_SECRET`	Client secret, shown once at registration

The CLI’s npm run register writes both to your backend .env. Your app manifest declares the service account under authentication.serviceAccount. See App Manifest: Authentication.

The client secret is shown once and cannot be retrieved afterwards. Keep it on your server, never in frontend code or a public repository.

Getting a Access Token

Your backend sends its credentials to the token endpoint using HTTP Basic authentication.

// lib/jtl-auth.ts
const AUTH_ENDPOINT = 'https://id.jtl-cloud.com/oauth2/token';
const API_BASE_URL = 'https://api.jtl-cloud.com';
const TOKEN_SCOPE = 'openid';


export async function getAccessToken(): 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 environment variables');
    }

    const credentials = 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 ${credentials}`,
        },
        body,
    });

    if (!response.ok) {
        const error = await response.json().catch(() => null);
        throw new Error(`Token request failed (${response.status}): ${error?.error || 'unknown'}`);
    }

    const data = await response.json();
    return data.access_token;
}

export { API_BASE_URL };

// JtlAuth.cs
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

public static class JtlAuth
{
    private const string AuthEndpoint = "https://id.jtl-cloud.com/oauth2/token";
    public const string ApiBaseUrl = "https://api.jtl-cloud.com";
    private const string TokenScope = "openid";

    private static readonly HttpClient HttpClient = new();

    public static async Task<string> GetAccessTokenAsync()
    {
        var clientId = Environment.GetEnvironmentVariable("CLIENT_ID");
        var clientSecret = Environment.GetEnvironmentVariable("CLIENT_SECRET");

        if (string.IsNullOrEmpty(clientId) || string.IsNullOrEmpty(clientSecret))
        {
            throw new InvalidOperationException(
                "CLIENT_ID and CLIENT_SECRET must be defined in environment variables"
            );
        }

        var credentials = Convert.ToBase64String(
            Encoding.UTF8.GetBytes($"{clientId}:{clientSecret}")
        );

        using var request = new HttpRequestMessage(HttpMethod.Post, AuthEndpoint);

        request.Headers.Authorization =
            new AuthenticationHeaderValue("Basic", credentials);

        request.Content = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("grant_type", "client_credentials"),
            new KeyValuePair<string, string>("scope", TokenScope)
        });

        var response = await HttpClient.SendAsync(request);

        if (!response.IsSuccessStatusCode)
        {
            string? errorCode = null;

            try
            {
                var errorBody = await response.Content.ReadAsStringAsync();
                using var errorDoc = JsonDocument.Parse(errorBody);

                if (errorDoc.RootElement.TryGetProperty("error", out var error))
                {
                    errorCode = error.GetString();
                }
            }
            catch
            {
                // Ignore parse failures and use "unknown".
            }

            throw new HttpRequestException(
                $"Token request failed ({(int)response.StatusCode}): {errorCode ?? "unknown"}"
            );
        }

        var json = await response.Content.ReadAsStringAsync();
        using var doc = JsonDocument.Parse(json);

        return doc.RootElement.GetProperty("access_token").GetString()
            ?? throw new InvalidOperationException(
                "Response did not contain an access_token"
            );
    }
}

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

namespace App\Jtl;

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
use RuntimeException;

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

    private static ?Client $httpClient = null;

    public static function getAccessToken(): string
    {
        $clientId = getenv('CLIENT_ID') ?: null;
        $clientSecret = getenv('CLIENT_SECRET') ?: null;

        if (!$clientId || !$clientSecret) {
            throw new RuntimeException(
                'CLIENT_ID and CLIENT_SECRET must be defined in environment variables'
            );
        }

        $credentials = base64_encode("{$clientId}:{$clientSecret}");

        try {
            $response = self::httpClient()->post(self::AUTH_ENDPOINT, [
                'headers' => [
                    'Content-Type' => 'application/x-www-form-urlencoded',
                    'Authorization' => "Basic {$credentials}",
                ],
                'form_params' => [
                    'grant_type' => 'client_credentials',
                    'scope' => self::TOKEN_SCOPE,
                ],
            ]);
        } catch (RequestException $e) {
            $status = $e->getResponse()?->getStatusCode() ?? 0;
            $errorCode = 'unknown';

            if ($e->hasResponse()) {
                $body = (string) $e->getResponse()->getBody();
                $decoded = json_decode($body, true);
                $errorCode = $decoded['error'] ?? 'unknown';
            }

            throw new RuntimeException(
                "Token request failed ({$status}): {$errorCode}",
                previous: $e
            );
        }

        $data = json_decode(
            (string) $response->getBody(),
            true,
            flags: JSON_THROW_ON_ERROR
        );

        return $data['access_token']
            ?? throw new RuntimeException(
                'Response did not contain an access_token'
            );
    }

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

curl -X POST 'https://id.jtl-cloud.com/oauth2/token' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'scope=openid'

The token endpoint requires HTTP Basic authentication. Sending the credentials in the request body instead of the Authorization header is rejected.

Token Response

A successful request returns:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 86399,
  "scope": "",
  "token_type": "bearer"
}

Field	Description
`access_token`	JWT used in the `Authorization: Bearer` header for API calls
`expires_in`	Token lifetime in seconds (approximately 24 hours)
`token_type`	Always `bearer`

Caching the Token

Access tokens are valid for approximately 24 hours. Requesting a new one on every API call adds latency and unnecessary load on the token endpoint. Hold the token in memory and request a new one shortly before it expires.

// lib/token-cache.ts
import { getAccessToken } from './jtl-auth';

let cachedToken: string | null = null;
let tokenExpiresAt = 0;
let inflightRequest: Promise<string> | null = null;

export async function getCachedAccessToken(): Promise<string> {
    const now = Date.now();
    const bufferMs = 60_000;

    if (cachedToken && now < tokenExpiresAt - bufferMs) {
        return cachedToken;
    }

    if (inflightRequest) {
        return inflightRequest;
    }

    inflightRequest = (async () => {
        try {
            const token = await getAccessToken();

            // Decode the JWT to read the expiry (without verifying, since we just received it)
            const payload = JSON.parse(
                Buffer.from(token.split('.')[1], 'base64url').toString()
            );

            cachedToken = token;
            tokenExpiresAt = payload.exp * 1000;

            return cachedToken!;
        } finally {
            inflightRequest = null;
        }
    })();

    return inflightRequest;
}

export function clearTokenCache(): void {
    cachedToken = null;
    tokenExpiresAt = 0;
}

// TokenCache.cs
using System.Text.Json;

public static class TokenCache
{
    private static string? _cachedToken = null;
    private static long _tokenExpiresAt = 0;
    private static readonly SemaphoreSlim _lock = new(1, 1);

    public static async Task<string> GetCachedAccessTokenAsync()
    {
        var now = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
        const long bufferMs = 60_000;

        if (_cachedToken != null && now < _tokenExpiresAt - bufferMs)
            return _cachedToken;

        await _lock.WaitAsync();
        try
        {
            now = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
            if (_cachedToken != null && now < _tokenExpiresAt - bufferMs)
                return _cachedToken;

            var token = await JtlAuth.GetAccessTokenAsync();

            // Decode the JWT to read the expiry (without verifying, since we just received it)
            var payloadBase64 = token.Split('.')[1];
            var paddedPayload = payloadBase64.PadRight(
                payloadBase64.Length + (4 - payloadBase64.Length % 4) % 4, '='
            );
            var payloadJson = System.Text.Encoding.UTF8.GetString(
                Convert.FromBase64String(paddedPayload)
            );
            using var doc = JsonDocument.Parse(payloadJson);
            var exp = doc.RootElement.GetProperty("exp").GetInt64();

            _cachedToken = token;
            _tokenExpiresAt = exp * 1000;

            return _cachedToken;
        }
        finally
        {
            _lock.Release();
        }
    }

    public static void ClearCache()
    {
        _cachedToken = null;
        _tokenExpiresAt = 0;
    }
}

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

namespace App\Jtl;

use RuntimeException;

final class TokenCache
{
    private static ?string $cachedToken = null;
    private static int $tokenExpiresAt = 0;

    public static function getCachedAccessToken(): string
    {
        $now = (int) (microtime(true) * 1000);
        $bufferMs = 60_000;

        if (self::$cachedToken !== null && $now < self::$tokenExpiresAt - $bufferMs) {
            return self::$cachedToken;
        }

        $token = JtlAuth::getAccessToken();

        // Decode the JWT to read the expiry (without verifying, since we just received it)
        $parts = explode('.', $token);
        if (count($parts) !== 3) {
            throw new RuntimeException('Invalid JWT format. Expected 3 dot-separated parts');
        }

        $payload = json_decode(
            self::base64UrlDecode($parts[1]),
            true,
            flags: JSON_THROW_ON_ERROR
        );

        self::$cachedToken = $token;
        self::$tokenExpiresAt = $payload['exp'] * 1000;

        return self::$cachedToken;
    }

    public static function clearCache(): void
    {
        self::$cachedToken = null;
        self::$tokenExpiresAt = 0;
    }

    private static function base64UrlDecode(string $input): string
    {
        $padded = strtr($input, '-_', '+/');
        $padded .= str_repeat('=', (4 - strlen($padded) % 4) % 4);
        return base64_decode($padded);
    }
}

The 60-second buffer prevents a token expiring between the cache check and the API call.

This in-memory cache works for a single-instance server. If you run multiple instances behind a load balancer, use a shared cache such as Redis so they do not each hold their own token.

Calling the API

Access tokens are not tied to a merchant, so every call names the tenant it applies to in the X-Tenant-ID header. Take that value from a verified app token rather than from the incoming request. See App Token Authentication. If a call returns 401 Unauthorized, clear the cached token and retry once with a fresh one.

// lib/api-client.ts
import { getCachedAccessToken, clearTokenCache } from './token-cache';

export async function callApiWithRetry(url: string, tenantId: string) {
    let token = await getCachedAccessToken();

    let response = await fetch(url, {
        headers: {
            Authorization: `Bearer ${token}`,
            'X-Tenant-ID': tenantId,
        },
    });

    if (response.status === 401) {
        clearTokenCache();
        token = await getCachedAccessToken();

        response = await fetch(url, {
            headers: {
                Authorization: `Bearer ${token}`,
                'X-Tenant-ID': tenantId,
                'Content-Type': 'application/json',
            },
        });
    }

    return response;
}

// ApiClient.cs
using System.Net.Http.Headers;

public static class ApiClient
{
    private static readonly HttpClient HttpClient = new();

    public static async Task<HttpResponseMessage> CallApiWithRetryAsync(string url, string tenantId)
    {
        var token = await TokenCache.GetCachedAccessTokenAsync();
        var response = await SendRequestAsync(url, tenantId, token);

        if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
        {
            TokenCache.ClearCache();
            token = await TokenCache.GetCachedAccessTokenAsync();
            response = await SendRequestAsync(url, tenantId, token);
        }

        return response;
    }

    private static async Task<HttpResponseMessage> SendRequestAsync(string url, string tenantId, string token)
    {
        var request = new HttpRequestMessage(HttpMethod.Get, url);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        request.Headers.Add("X-Tenant-ID", tenantId);
        request.Headers.Add("Content-Type", "application/json");
        return await HttpClient.SendAsync(request);
    }
}

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

namespace App\Jtl;

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\Psr7\Response;

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

    public static function callApiWithRetry(string $url, string $tenantId): Response
    {
        $token = TokenCache::getCachedAccessToken();
        $response = self::sendRequest($url, $tenantId, $token);

        if ($response->getStatusCode() === 401) {
            TokenCache::clearCache();
            $token = TokenCache::getCachedAccessToken();
            $response = self::sendRequest($url, $tenantId, $token);
        }

        return $response;
    }

    private static function sendRequest(string $url, string $tenantId, string $token): Response
    {
        try {
            return self::httpClient()->get($url, [
                'headers' => [
                    'Authorization' => "Bearer {$token}",
                    'X-Tenant-ID' => $tenantId,
                    'Content-Type' => 'application/json',
                ],
                'http_errors' => false,
            ]);
        } catch (RequestException $e) {
            return $e->getResponse() ?? throw $e;
        }
    }

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

Scope Enforcement

Calls made with a access token are bound by the scopes declared in capabilities.erp.api.scopes in your manifest. A call that exceeds them returns 403 Forbidden. This holds even when a merchant is signed in. A backend that verifies an app token and then calls the API with its service account is making a machine call, so the manifest’s scopes apply rather than the merchant’s own permissions. See Scopes & Permissions.

Common Errors

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

401 Unauthorized: invalid_client

The CLIENT_ID or CLIENT_SECRET is incorrect. Check both values in your .env for extra whitespace, missing characters, or swapped values. If the secret has been lost, register a new app version in the Partner Portal to receive fresh credentials.

401 Unauthorized on a call that worked earlier

The cached token has expired. Clear the cache and request a new one, as the retry example above does. If this happens often, confirm the cache is reading exp from the token rather than assuming a fixed lifetime.

400 Bad Request on the token request

The credentials were sent in the request body. The token endpoint requires HTTP Basic authentication, so they belong in the Authorization header.

403 Forbidden on an API call

The token is valid, but the call exceeds the scopes declared in your manifest. Add the scope your app needs and submit an updated manifest through the Partner Portal.

API calls fail with a tenant error

The X-Tenant-ID header is missing or names a tenant your app is not installed on. Take the value from a verified app token’s urn:jtl:tenant_id claim.

What’s Next?

App Token Authentication

Verify the app token that tells your backend which merchant a request belongs to.

Using Platform APIs

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

Scopes & Permissions

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

Best Practices

Production patterns for token caching, error handling, and security.

Essentials

Cloud Apps

ERP Integration

Before You Start

Getting a Access Token

Token Response

Caching the Token

Calling the API

Scope Enforcement

Common Errors

What’s Next?

App Token Authentication

Using Platform APIs

Scopes & Permissions

Best Practices

​Before You Start

​Getting a Access Token

​Token Response

​Caching the Token

​Calling the API

​Scope Enforcement

​Common Errors

​What’s Next?

App Token Authentication

Using Platform APIs

Scopes & Permissions

Best Practices

Before You Start

Getting a Access Token

Token Response

Caching the Token

Calling the API

Scope Enforcement

Common Errors

What’s Next?