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 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.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’sclientId. Don’t forward the ID
token, or a token issued to another client — the MarketBox dashboard’s or
another Application’s.
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 anACTIVE membership whose roles grant the route’s
permission:
- A client gets an
ACTIVEmembership with theCLIENTrole 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
ACTIVEmembership with theSUPPLIERrole by accepting the business’s invitation in the dashboard.
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.
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.