Authentication
Send both headers on every request:
| Header | Meaning |
|---|---|
x-api-key | Your partner API key, issued per organization. Treat it as a secret. |
x-mealco-org-id | The organization the call acts on behalf of. |
They are required together, and the organization id must be the organization the key belongs to. A mismatch is rejected with 401. It is not reinterpreted as the key's own organization.
Scope
A credential is scoped to exactly one organization. There is no request parameter that widens that scope, which is why organizationId never appears in a request body: an operation cannot be pointed at data the credential does not already reach.
Handling keys
- Keep the key server-side. It is a bearer credential: anyone who holds it can act as you.
- Rotate by requesting a new key, moving traffic to it, then retiring the old one. Both are live during the overlap, so a rotation needs no downtime window.
- If a key is exposed, contact support@yoursouschef.com immediately. A compromised key is revoked, not rotated on a schedule.
Rate limits
Rate limits apply per organization and per kind of operation. Directory and status reads have the highest limit. Paged reads such as fetchOrders have a lower one. Writes that reach the delivery platforms, menu publishing and report requests have the lowest. Every limit is counted over a 60-second window.
- A limit is per organization, not per key. All of your keys draw on the same budgets, so adding keys does not multiply your throughput and rotating a key does not reset your usage. Send
x-mealco-org-idon every request. It is required for authentication. 429is part of the contract. Any operation may answer it. HonourRetry-Afterwhen it is present; when it is not, wait 60 seconds and add jitter. Either way, do not tight-loop. See Getting Started → Errors and retries.
Two properties of the API keep a polling integration inside its limits:
- Store, status, menu and order reads are answered from Sous Chef's own refreshed state, never proxied per request to the platforms. Your cadence is bounded by your limits alone, never by a platform's. The Uber Eats promotion reads are the exception: they call Uber Eats on each request. See Concepts → Data freshness.
- Reads are bulk-shaped.
fetchStoreStatusestakes many storefronts in one call, andfetchStorespages through the whole crosswalk at up to 100 rows a page. A status sweep across a large estate is a handful of calls, not one per store.
If your expected volume needs more than the standard limits (for example, a frequent status sweep across every store), send the cadence you need to support@yoursouschef.com.
What a failure looks like
401: the key is missing, unknown, revoked, or does not match the organization id.403: the key is valid but does not have the permission that the operation needs, for example a read-only key on a write.429: you are over your rate limit. See Rate limits above and Errors and retries.