Authentication

Every Zendera API request authenticates with an API key sent as a header. This article covers the format, lifecycle, and common pitfalls.

How it works in one paragraph

Your API key is an opaque key generated by your admin in the Zendera admin UI. You don’t generate or sign anything yourself — an admin creates the key, you store it, and you send it back on every request in the Authorization header using the apikey scheme (Authorization: apikey <YOUR_API_KEY>). There’s no refresh and no automatic expiration; rotate or revoke it from the admin UI when needed.

Base URLs

• Production: https://app.zenderatms.com/api/
• Staging: https://staging.zenderatms.com/api/

Header format

Authorization: apikey <YOUR_API_KEY>

That’s the literal word apikey (lowercase), then a space, then the key your admin generated — not Bearer.

Common mistakes that cause 401:

What the key looks like

The API key is an opaque token generated by Zendera — there’s nothing for you to decode, sign, or inspect. Treat it as a secret string and send it exactly as issued.

• No automatic expiry — a key stays valid until you rotate or revoke it.
• No user identity — every action made with the key is attributed to your organization, not to a specific person.

Getting Your API Key

This is done by your Zendera admin in the UI:

How to rotate or revoke an API key

API keys have no expiry. There’s nothing to refresh — instead you rotate or revoke manually. The key lifecycle is managed in the Zendera admin panel, which is backed by POST /v2/organization/apikey (create/rotate) and DELETE /v2/organization/apikey (revoke):

• Rotate — Admin opens Settings → Integrations → API keys, finds the key, and creates a replacement. Zendera issues a new key (revealed once). Coordinate the cut-over with your developers, then revoke the old key.
• Revoke — From the same screen, revoke the key. Effective immediately; all requests with the old key start returning 401.

Smoke-test endpoint

The simplest call for verifying your auth works is the orders-by-date list (GET /v2/orders/summary/listbydate). A 200 OK with an orders array (possibly empty) means auth is working. A 401 means a header-format issue.

If you already know an order’s internal number, GET /v2/orders/summary/internal/{internalOrderNumber} is an equally good single-resource smoke test.

Status codes you’ll see

What an API key cannot do

The integration role is deliberately narrow. It cannot:

• Create / modify / delete users, organizations, customers, departments, vehicles, products (catalog), order types, zones, freight levels, price lists.
• Issue, rotate, or revoke API keys (that’s an admin action in the Zendera UI).
• Create or update orders directly — orders go through POST /v3/orders/import.
• Change order status — status changes are a side effect of driver actions in the mobile app.

It can:

• Import orders (single or bulk) via /v3/orders/import.
• Read orders by internal number, by date, and via the status feed.
• Cancel and replan orders.
• Reserve and revoke tracking links.
• Attach documents to orders.
• Read and set vehicle type; read completion proof.
• Read driver-recorded order events (deviations, comments, photos, signatures).
• Manage drivers and their workdays.
• Create document records and upload files.
• Book orders and drafts on route-scheduling intervals; manage schedules and intervals.
• Manage recurring-order templates.
• Search and list locations; read their contacts and time windows; manage location records (v1).
• Granular product CRUD via /v1/order-products/upsert.
• Read and patch the atoms tree.
• Define organization-wide custom fields.
• Manage cargo-carrier accounting (linking products, balances, submissions).
• Search email and SMS notification logs.

If you call something outside this surface, you’ll get 403 Forbidden.

Multi-environment recommendation

Treat staging and production as separate orgs with separate keys:

Don’t try to point a staging key at production — they’re different orgs and the key won’t authenticate.

Logging and observability

• Every API request is logged on Zendera’s side with timestamp, endpoint, key, and request/response summary. Available in the admin UI’s audit log.
• Don’t log API keys in your own logs. If you must, redact to the first/last 4 characters.