Conventions
Authentication
The authentication contract of the Transactions API, endpoint by endpoint, with lifetimes and permissions
Updated on 2026-08-16For: Developers
This page is the Transactions API v1 contract. For the step by step, see the Authentication guide. The Catalog API and Transactions API v2 use a different scheme: an API key and secret against the Authorization API, with a token that carries no shops.
Scheme
| Concept | Value |
|---|---|
| Type | Signed JWT issued by the Transactions API |
| Issuing endpoint | POST /api/v1.0/Token |
| Transport | Authorization header |
| Header format | Bearer + space + token |
| Lifetime | 2 days from issue |
| Renewal | No refresh: request a new one with username and password |
| Required permission | ApiUser role in BistroWeb |
| Data scope | The shop_code claims inside the token |
| Revoking access | Disabling the user stops new tokens from being issued; one already issued stays valid until it expires |
Every endpoint requires a token
Every read endpoint requires the Authorization header. The only anonymous endpoint
is POST /api/v1.0/Token, which issues it. There are no public endpoints and no
IP-based authentication. API keys do exist, but they belong to the Authorization API
and serve the Catalog API and Transactions API v2, not this one.
Request body
{
"username": "integrations@company.com",
"password": "..."
}
Both fields are required and are BistroWeb credentials, not a separate secret.
Response
{
"token": "eyJ...",
"expiration": "2026-08-18T13:04:22Z"
}
expiration is UTC, in the ISO 8601 format described in
Dates and time zones.
Declared scheme versus real behaviour
Security is declared as {"type": "apiKey", "in": "header", "name": "Authorization"} instead of {"type": "http", "scheme": "bearer"}. It is a
declaration mismatch, not a behavioural one: the server still expects the
Bearer prefix. It matters because client and snippet generators emit a raw
header from that declaration. If a generated client returns 401 with a token you
know is good, inspect the exact header value.
This portal normalizes the scheme when loading the spec, so the code samples here already carry the correct prefix.
What the portal lets you try
- In preproduction, the portal can ask for credentials to issue a test token.
- In production, the portal never asks for a password: it only accepts a token you paste, and only read methods can be executed.
A documentation site that asks for production credentials trains users to do exactly what phishing does.