x-api-key header. The key identifies your application and behaves
as a long-lived service credential, minted in the MarketBox dashboard.
Some routes also act on behalf of a signed-in end user and additionally
require a per-user token: the client’s /clients/me routes and the supplier’s
/suppliers/me routes. Those routes are the exception — most of the API
needs only the API key. See
End-user authentication for those planes
and when you need them.
One route takes a third credential: the browser beacon for site events,
POST /v1/projects/{projectId}/events/beacon, takes a publishable key in
its query string instead of an API key. See
Report site events.
The header
When the key is missing or wrong
A request with nox-api-key, or one carrying a key MarketBox does not
recognise, is rejected at the edge with 403 — before any business logic
runs, and before your key’s project scope is evaluated at all. It returns the
same error envelope as every other MarketBox error, so you can read code here
exactly as you do everywhere else:
code, with "message": "No such route". The two are 403 for the
same reason — the edge refuses them before it knows anything about you — so the
message is what tells them apart.
Because these are rejected before your request reaches the application, the
requestId here is the gateway’s own id rather than an X-Request-Id you
supplied. Quote it when contacting support; it is still the id that identifies
your request in our logs.What a key carries
When you mint a key in the dashboard, MarketBox stores the following metadata against it:
The raw key value is shown once, at create time. MarketBox stores only
the hash — if you lose it, you must mint a new one.
Project scope
projectScope is an array of project ids that gates every authenticated
call. There are three meaningful shapes:
Mixing the wildcard with an explicit id (e.g.
["*", "prj_01h2xcejqtfzcjxkvc4ay3pnh3"]) is
rejected at create time as malformed.
The wildcard expands only within the owning user’s blast radius — it
never crosses users. A compromised wildcard key from one user can never
touch another user’s projects.
Scope enforcement
Every tenant-scoped endpoint has a{projectId} path parameter. On each
request, the API:
- Validates the API key and resolves it to its scope.
- Reads
{projectId}from the URL. - Checks
scope.includes("*") || scope.includes(projectId). - Returns
403if not allowed.
403 — not a 404 — if a project exists but your key isn’t
scoped to it. A 404 means the project itself doesn’t exist.
Capabilities
Project scope says which projects a key may act on. Capabilities say which kinds of route it may call. A project admin sets them on the Application, on the API Access page of the dashboard:
Two rules to know:
*doesn’t include the event capabilities. A key reports site events only ifevents:writewas granted by name. Without it, the events route answers403 FORBIDDEN.- A key without
*can call nothing else. A key with no capabilities ticked, or only Site events, is refused on every other route — before the project, the user token or any data is read.
*. It keeps working as before.
When the key lacks Standard API access
code, and a message
naming what it holds. To fix it, a project admin ticks Standard API access
on the Application. A key may hold * and events:write together.
Test keys and sandbox
MarketBox has one kind of API key. There are no test keys, and there is no sandbox.- Every key is live. A key acts on the real data of its project. A booking you create claims the supplier’s time, and MarketBox sends the emails it sends for any booking.
- Card payments are live too. A card you charge through Accept payments with Stripe is really charged. Stripe’s test cards are declined.
Rotating keys
To rotate:- Mint a new key with the same scope in the dashboard.
- Roll out the new key to your callers.
- Revoke the old key once traffic is fully off it.
Tenancy
Every write (POST, PATCH, DELETE) is tagged with the API key’s
owning userId as tenantId on the underlying record. tenantId names
the user, not the key: every key that user owns writes the same
tenantId, so it can’t tell you which of them made a change. MarketBox
records the acting key separately, by its key id (apiKeyId), in its own
audit trail. That id isn’t returned on records. To tell your own callers
apart, give each one its own key and log which key each call used.
You don’t pass tenantId yourself — MarketBox derives it from the key on
the server.