Public beta

Authentication

Every request to the Zippex API must include a valid API key. Keys are scoped to your Zippex account and determine whether requests run in test or live mode.

API key types

Key prefix	Mode	Description
`zx_test_`	Test	Sandbox environment. No real drivers are dispatched and no charges are made. Deliveries follow a simulated lifecycle.
`zx_live_`	Live	Production environment. Real drivers, real charges. Use only after you have tested your integration thoroughly.

How to authenticate

Pass your API key as a Bearer token in the Authorization header on every request.

curl https:"color:#6a9955">//developer.zippex.app/api/v1/deliveries \
  -H "Authorization: Bearer zx_live_your_api_key_here"

"color:#6a9955">// zippex.js, simple API wrapper
const ZIPPEX_API_KEY = process.env.ZIPPEX_API_KEY; "color:#6a9955">// zx_live_... or zx_test_...

async function zippex(path, options = {}) {
  const response = await fetch(`https:"color:#6a9955">//developer.zippex.app/api${path}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${ZIPPEX_API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  return response.json();
}

"color:#6a9955">// Usage
const quote = await zippex('/v1/quotes', {
  method: 'POST',
  body: JSON.stringify({
    pickup_address: '350 W Georgia St, Vancouver, BC',
    dropoff_address: '2085 Main St, Vancouver, BC',
  }),
});

Store the key in your server environment and inject it into outbound API requests. Do not expose live keys in frontend code, mobile bundles, or public repositories.

Test mode vs. live mode

The mode is determined entirely by the API key prefix. There is no separate endpoint or environment toggle.

Behavior	Test mode	Live mode
Driver dispatch	Simulated	Real drivers
Charges	Stripe test mode — pay with test cards (e.g. 4242…), no real money	Real charges
Webhooks	Delivered to your endpoint with test payloads	Delivered with live payloads
Delivery lifecycle	Auto-advances through statuses on a timer	Real-time updates from driver app
Rate limits	Same as live	Per-developer limit (default 60 req/min)

Recommended workflow: build and verify the full quote, delivery, tracking, and webhook flow with a zx_test_ key first, then replace only the key when you are ready for production.

Key rotation best practices

Store keys in environment variables, never commit them to source control.
Rotate keys periodically, generate a new key from the API Keys page. Rotation invalidates the previous key immediately. Deploy the new key first, then rotate.
Save your key when it is shown, Zippex stores only a hash of your key. We cannot recover a lost key; rotate to issue a new one.
Use separate keys per environment, your staging server should use a test key, and production should use a live key.
Revoke compromised keys immediately, if a key is leaked, revoke it in the dashboard. Revocation takes effect within 60 seconds.

Authentication errors

If the API key is missing or invalid, you will receive a 401 response:

401 Unauthorized

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "param": null
  }
}

See the Errors page for a full list of error types and codes.

Next step: continue to Quotes to request pricing with your test key.