Authentication

The platform exposes four API surfaces and uses two different authentication mechanisms across them. Pick the one that matches the surface you are calling.

API	Mechanism
Reseller API	JWT bearer token
Storefront API	JWT bearer token
Payment API	API key
Supplier API	API key

---

JWT token

The Reseller and Storefront APIs are authenticated with a JWT bearer token. The Reseller API token is issued to a partner account via Generate Token, while the Storefront API token is issued to an end-user customer via the login flow.

Sending the token

The platform expects the token in the Authorization header — with the Bearer prefix:

POST /Orders/Create HTTP/1.1
Host: {{apiHost}}
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

warning

Sending the header without the Bearer prefix returns 401 Unauthorized.

Token lifecycle

• Tokens are HS256-signed and expire depending on use after issue.
• Refresh by calling the login endpoint again before expiry, or implement client-side middleware that refreshes on the first 401.
• Token claims include the customer identifier, tenant and any scope restrictions configured server-side.

Failure modes

Status	Cause
401	Missing header, malformed token or expired.
403	Token is valid but lacks the required scope.

---

API key

The Payment and Supplier APIs are called by trusted server-to-server integrations. They authenticate with a long-lived API key transmitted in a dedicated request header.

Sending the key

POST /Supplier/Products/List HTTP/1.1
Host: {{apiHost}}
ApiKey: ak_live_8f3b1c0e5a4d4f2c9b1e7d6c5a4b3c2d
Content-Type: application/json

The header name is ApiKey (case-insensitive). It is the only required authentication header, no signature.

Storage & rotation

• Treat the key as a secret. Store it in a secret manager (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, …) — never in source control, never in browser bundles.
• Rotate immediately on suspected leak; the old key can be revoked instantly.

Failure modes

Status	code	Cause
401	-23	ApiKey header missing, malformed, expired, revoked, or the key does not belong to the requested tenant.
403		Key is valid but the tenant lacks access to the called endpoint.

See Errors for the full numeric error-code catalogue.