Skip to main content
The MarketBox API authenticates every request with an API key carried in the 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

The key value is an opaque string. It has no prefix, and nothing in it names an environment or a project.

When the key is missing or wrong

A request with no x-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:
A request to a path the API does not serve is rejected the same way and carries the same 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:
  1. Validates the API key and resolves it to its scope.
  2. Reads {projectId} from the URL.
  3. Checks scope.includes("*") || scope.includes(projectId).
  4. Returns 403 if not allowed.
You’ll get a 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 if events:write was granted by name. Without it, the events route answers 403 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.
A key minted before capabilities existed carries no list, and is treated as *. It keeps working as before.

When the key lacks Standard API access

A key that holds only some capabilities gets the same 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.
To try the API without touching a live business, use a separate project. Each project has its own services, suppliers, clients, bookings and orders, and a key minted in one project can’t read or write another. Create your test services, suppliers and clients there, and use people and email addresses you control.

Rotating keys

To rotate:
  1. Mint a new key with the same scope in the dashboard.
  2. Roll out the new key to your callers.
  3. Revoke the old key once traffic is fully off it.
Keys cannot be edited in place — name and scope are immutable after creation. Rotation = mint + revoke.

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.