Authentication

Requests are authenticated with a short-lived bearer token. Your client secret is used only to obtain that token, never on ordinary requests.

Why not a static key

A static API key travels over the wire on every single request and, if it leaks, stays valid until someone notices and revokes it. A token limits both: the secret moves once an hour, and a leaked token expires on its own.

Getting a token

POST /api/vendor/v1/token
Content-Type: application/json

{
  "clientId": "your-client-id",
  "clientSecret": "hzl_live_..."
}

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600
  }
}

Send it on every other call:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Cache the token, renew it early

This is the one mistake that costs deliveries

If a token expires mid-request, the order is rejected with 401 — and we do not retry it. The package waits while your system figures out what happened.

Renew about five minutes before expiry. Do not wait for a 401 to tell you.

Requesting a token before every order also wastes a round trip and will hit the token rate limit (60 per hour). If you are anywhere near that limit, you are not caching.

Handling 401

Two different failures share the status code. The WWW-Authenticate header and errorCode tell them apart.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="expired"

errorCode	Meaning	What to do
TOKEN_EXPIRED	Token aged out	Get a new token, resend the request once
INVALID_CREDENTIALS	Secret is wrong, revoked, or the account is suspended	Stop. Retrying will not help — contact us

Resending after TOKEN_EXPIRED is your retry, and it is correct. It is different from us silently retrying a failed order in the background, which we never do.

Protecting the secret

• Never embed the secret in a mobile app, a browser bundle, or anything that runs on a device you do not control. It belongs on your server.
• Never share it with the restaurants using your POS.
• Rotate it if you suspect exposure. During rotation, tokens already issued stay valid for their remaining hour, so rotation does not cause an outage.
• Tell us within 24 hours if you think it leaked. We can revoke immediately.

Environments

Environment	Secret prefix	Base URL
Sandbox	hzl_test_	https://gw-dev.hizliyo.com/api/vendor/v1
Production	hzl_live_	https://gw.hizliyo.com/api/vendor/v1

Sandbox credentials are issued first. Production credentials arrive after you complete the launch checklist.

Transport

TLS 1.2 or higher is required. Older handshakes are refused at the connection level, before any application code runs — if you see a connection reset with no HTTP response, check your TLS configuration first.