Skip to main content
Most MarketBox API calls are made by your application and authenticate with an API key. But some flows act on behalf of a signed-in person — for example, “show me my bookings” or “use my remaining credits”. Those routes require a second credential: a user token obtained when the person signs in. This page explains the model. For step-by-step integrations, see Build a booking flow and Build a supplier portal.

Two credentials

Every request to an end-user route carries two credentials, each with a distinct job: The API key proves which integration is calling. The user token proves which person the call is for. End-user routes need both; everything else needs only the API key (see Authentication).

Two end-user planes

The end-user routes form two planes. Each acts on the signed-in person’s own record, and never takes that record’s id from the path or the body:

The golden rule

The API key is a server-only secret. Your browser must never see it.
The browser holds only the user token and sends authenticated requests to your own backend. Your backend attaches the API key before forwarding to MarketBox. This is non-negotiable: leaking the API key gives anyone access to your project’s entire client data.
This shape is the backend-for-frontend (BFF) pattern: a thin server you own that is the only place the API key lives.

Where the user token comes from

End users sign in through MarketBox hosted login using the OAuth 2.0 Authorization Code flow with PKCE. Your app redirects the person to the hosted sign-in page; after they authenticate, MarketBox redirects back to your callback URL with an authorization code, which you exchange for tokens. Forward the access token your own Application’s client issued. That is the token from signing in with your Application’s clientId. Don’t forward the ID token, or a token issued to another client — the MarketBox dashboard’s or another Application’s.
Today a token from another client is logged and the request still goes through. Once enforcement is switched on, it is a 401 UNAUTHORIZED. Send your own client’s access token now, and nothing changes for you when it is switched on. On the client plane, MarketBox’s own booking flow stays accepted; on the supplier plane, it doesn’t.
You configure the OAuth client and endpoints once — see Build a booking flow for the full walkthrough.

Who may call an end-user route

Both planes check the person’s membership of the project on every request. The person must hold an ACTIVE membership whose roles grant the route’s permission:
  • A client gets an ACTIVE membership with the CLIENT role from onboarding, POST /v1/projects/{projectId}/clients/me. Onboarding is the one end-user route that needs no membership — it creates it.
  • A supplier gets an ACTIVE membership with the SUPPLIER role by accepting the business’s invitation in the dashboard.
A live client profile or supplier record doesn’t help on its own. When the business removes the person’s role in the dashboard, their next call is refused. On the supplier plane, GET /suppliers/me/access answers the same question with a 200 and a reasonCode, so your portal can check on sign-in. See Check access first.
Not every 401 means “sign in again”. A missing or publishable API key is also a 401, and so is a token without a sub. Signing the person in again fixes neither, so a client that re-logs on every 401 loops forever. Re-authenticate only on a 401 whose code is HTTP_ERROR (no token, a malformed header, or an invalid or expired token). Treat a 401 UNAUTHORIZED as a bug in your backend and log it.
A client whose access was removed and who calls onboarding again gets 403 MEMBERSHIP_INACTIVE, with the message “Your access to this business was removed. Ask them to invite you again.” Nothing is read or linked.