Authentication

Each API call to Logitrail API must have two mandatory authentication headers, unless otherwise specified in the endpoint documentation.

• Authentication: Bearer <access token>
• X-Logitrail-Merchant-ID: <merchant id>

The <merchant id> is a fixed value for your merchant account. The <access token> you'll obtain from the token endpoint as described below.

Client Registration

Each client connecting Logitrail API must be registered in advance. Logitrail's Customer Service will provide you Client ID and Client Secret upon request. The client credentials are confidental.

To register a client, we require following details:

• One or more technical contact e-mail address(es)
• Name of the client system
• What API operations are expected to be used (see scopes below)
• Is the client test or production client?

Obtain an Access Token

To obtain an access token, a standard OAuth2 Client Credentials flow is used. For security reasons it's recommended to use an existing, well-maintained library or framework to obtain the token.

• The token endpoint is https://idp.logitrail.com/realms/logitrail/token for both test and production systems
• Client ID and Client Secret are provided in the HTTP Basic Authentication Header
• Define the scopes you need to use the token in the request body in standard way
• You will get the access token as a response in access_token parameter

The provided token is valid only for a certain period, maximum 24 hours. Lifetime is provided in a standard expires_in field with the token. Please note in your implementation that the validity period may vary.

Token Scopes

Each token can be used only for operations defined in the scopes when requesting the token. For security reasons, it's preferred that you request only minimum scopes, but actual implementation is up to your system architecture and requirements.

You find the required scopes for each API operation from the corresponding endpoint documentation.

Available scopes

The merchant API surfaces the following scopes. :read allows GET-style operations; :manage allows write operations (create / update / delete). They are separate scopes: a token holding :manage does not automatically satisfy an endpoint that requires :read. Request both when your integration performs both reads and writes — multiple scopes may be passed space-separated in the token request.

Scope	Purpose
orders:read	Read order data
orders:manage	Create / update / cancel orders
order_returns:read	Read order returns
order_returns:manage	Create / update order returns
products:read	Read product profiles
products:manage	Create / update product profiles
inbound_shipments:read	Read inbound shipments and their items
inbound_shipments:manage	Create / update inbound shipments
pickup-points:read	Read pickup point catalog
pickup-points:manage	Manage pickup point configuration
pricing:read	Read merchant pricing
pricing:manage	Manage merchant pricing
merchants:read	Read merchant account data
merchants:manage	Manage merchant account data
webhooks:manage	Configure webhook deliveries
warehouse-management:read	Read warehouse configuration

Naming convention

Most scopes use a hyphen as the separator (pickup-points:read), but inbound_shipments and order_returns use an underscore. This is a historical inconsistency — pass the exact strings shown above.

Per-client scope allowlist

Each client is configured with an explicit list of scopes it is allowed to request. If you ask the token endpoint for a scope that is not on your client's allowlist, the request fails with HTTP 400 and an error body of the form:

{ "error": "invalid_scope", "error_description": "Invalid scopes: <scope>" }

This means the scope itself is recognised by the platform, but your client has not been granted access to it. To resolve, contact Logitrail Customer Service with your Client ID and the list of scopes you need; we'll update the client configuration. Do not silently drop the scope from your token request — you'll get a token, but subsequent API calls that require the missing scope will return 403.

When introducing a new integration, list every scope you intend to use as part of the client registration request so the allowlist is set up correctly from the start.

Moving from Test to Production

Each client is limited to access either test or production environments. When you are ready to move to production, please request a new client for the production environment.

Note that the same token endpoint is used for both test and production, while actual Logitrail API endpoints are different.