Authentication¶

Last updated October 19, 2026

Every request carries a bearer token in the Authorization header. There is no other authentication mechanism — no query-string keys, no HMAC on requests, no OAuth.

Authorization: Bearer omni_sk_YOUR_KEY

Key format¶

Keys always begin with omni_sk_. A token without that prefix is rejected before any database lookup.

Keys are shown once at creation and stored as a SHA-256 hash. Lose it and staff issue a new one — nobody can read the original back.
One active key per seller is the norm.
The key resolves to exactly one seller account. Every endpoint is scoped to the orders that account fulfils: an order is visible once it is routed to you. If you are a fulfilment partner, that includes orders routed to you from other sellers, and your own orders that are routed to another warehouse partner are not visible to your key.

Revocation¶

Revocation is immediate. A revoked key fails on its very next request, with no grace period or cache.

Server-side storage only¶

The API is not CORS-restricted, but a key in browser or mobile code is a key you have published. Store keys server-side only.

Error responses¶

401 — No key, or a token without the prefix

{
  "error": "missing_api_key",
  "message": "An Authorization: Bearer API key is required."
}

401 — Key not recognised, or revoked

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or has been revoked."
}

A wrong key looks like an empty account¶

Authentication failures return 401, but authorisation failures do not return 403. If a key belongs to a different seller than the order you are asking for, you get 404 not_found — identical to an order that does not exist. If a known-good order ID is 404ing, check which seller the key belongs to before you assume the order is missing.

Orders waiting on an Omnishelf label are not visible yet¶

Some orders ship on a label that Omnishelf supplies. Until that label is attached, the order is left out of GET /v1/fulfilment-orders, and the order, its shipments, parcels, labels and tracking all return 404 not_found. The order appears as soon as the label is ready. No action is needed on your side.