Authentication
The data API uses API keys sent as a bearer token. The tracking lookup is public and needs no key.
Getting a key
A ZargoLogix administrator creates keys in the Integration Center of the admin dashboard, on the API keys tab. Each key has a name, the scopes it may use, an optional expiry date and an optional rate limit of its own.
Keys start with zlx_live_. Treat a key like a password: keep it on your server, never in a web page, mobile app or public repository.
Sending the key
Send the key in the Authorization header of every request:
Header
Authorization: Bearer zlx_live_YOUR_KEYcurl
curl -H "Authorization: Bearer zlx_live_YOUR_KEY" \
"https://api.zargologix.com/v1/invoices?status=OVERDUE"Scopes
A key can only read what its scopes allow. Asking for anything else returns 403 insufficient_scope.
| Scope | Allows | Pages |
|---|---|---|
| shipments:read | GET /v1/shipments… | List and read shipments, including their event history. |
| invoices:read | GET /v1/invoices… | List and read invoices, including line items and payments. |
| quotes:read | GET /v1/quotes… | List and read quotes, including line items. |
Give each integration its own key with only the scopes it needs, so one leaked key does not expose everything.
When authentication fails
| Situation | Status | Error code |
|---|---|---|
| No key, or not a ZargoLogix key | 401 | unauthorized |
| Unknown key | 401 | unauthorized. The message is the same as for a missing key on purpose. |
| Key was revoked | 401 | key_revoked |
| Key has expired | 401 | key_expired |
| Key lacks the scope | 403 | insufficient_scope |
Good practice
- Rotate keys by creating the new key first, switching your system over, then revoking the old one.
- Set an expiry date on keys you hand to partners or contractors.
- If a key may have leaked, revoke it straight away. Revoking takes effect on the next request.