/v1/projects/{projectId}/suppliers/me.
A supplier portal signs in exactly as a booking flow does. This page covers
what is specific to suppliers. For creating an Application, hosted sign-in
(PKCE) and the backend-for-frontend (BFF) pattern, see
Build a booking flow.
Before you start
- An Application. A project admin creates one on the API Access page of
the dashboard. It gives you an API key for your server and a
clientIdfor your sign-in page. The key needs Standard API access. See Capabilities. - The supplier is a member of the project. The business invites the
supplier from the dashboard, and the supplier accepts. That gives them an
ACTIVEmembership with theSUPPLIERrole, linked to their supplier record. Your portal can’t add a supplier to a project. - One sign-in. A supplier has one MarketBox sign-in. They sign in to your portal with the account they accepted the invitation with.
Credentials and the token
Every supplier-plane request carries two credentials:
Send the access token your Application’s own client issued. That is the
token from signing in with your Application’s
clientId. Don’t send the ID
token. Don’t forward a token issued to another client — the MarketBox
dashboard’s, another Application’s, or MarketBox’s own booking flow.
A request with the API key but no token is a 401. A request with no API key,
or with a publishable key in x-api-key, is a 401 too. Read the message
before you sign the supplier out. “API key not provided” and “A publishable
key cannot be used as an API key” mean your BFF sent the wrong key. Signing in
again can’t fix that, and a portal that tries loops. Sign the supplier in again
only on a 401 HTTP_ERROR. Treat any 401 UNAUTHORIZED as a bug in your BFF
and log it. See
End-user authentication.
Who may call it
Before a route runs, the API checks, in this order:- Your API key, its capabilities and its project scope.
- The user token.
- The person’s membership of the project.
- Their supplier record in this project.
ACTIVE membership whose roles grant the route’s
permission. A supplier holds all four permissions:
Everyone acts as a supplier here. A project admin or manager who also has a
supplier record acts on their own record only, never on someone else’s. A
manager is refused on demand and search insights.
Check access first
GET /v1/projects/{projectId}/suppliers/me/access answers one question: may
this signed-in person use the supplier plane here, and if not, why? Call it
on sign-in, and again whenever your portal renews its own session. Send
the same two credentials as every other supplier-plane route.
200 for every outcome about the
person. One call tells your portal which screen to show. A current supplier
gets this:
SUPPLIER role was removed, and who kept CLIENT, gets this:
SUPPLIER_RECORD_INACTIVE is your call. The data routes still serve an
inactive supplier (see When access ends), but the access
route reports allowed: false so you can decide what your portal does.
The route describes the person, not one acting role, so it ignores
X-MB-Acting-Role. roles lists everything they hold.
The access route still fails when your credentials are wrong, with the same
errors as the data routes: a missing or invalid token is 401, a key without
Standard API access is 403 CAPABILITY_NOT_GRANTED, and a project outside the
key’s scope is 403 FORBIDDEN. See Refusals.
When the access route and a data route differ
The data routes refuse with the same codes and messages as the access route. Two things can still make their answers differ:- An inactive supplier record. The access route says
SUPPLIER_RECORD_INACTIVE, withallowed: false. The data routes answer200. X-MB-Acting-Role. A data route judges the request on the role the header names. A person who holdsSUPPLIERbut sendsX-MB-Acting-Role: CLIENTgets404 NO_SUPPLIER_ROLEon the bookings routes, even with a linked supplier record, while the access route allows them. Acting as a client, a person’s “my” views are those of the person receiving the service, never a supplier’s schedule. The alerts routes always read the supplier’s own inbox, whatever the header names. Your portal doesn’t need the header: send none.
Refusals
Every refusal uses the standard error envelope. Branch oncode, not on the status. The same cause can come back as 403 on one route
and 404 on another.
A person whose access ended sees this:
SUPPLIER role was removed, and who kept CLIENT, sees this on
GET /suppliers/me/bookings:
Before November 5, 2026, these refusals were
403 FORBIDDEN
(“No active membership on this project”, “Insufficient permissions for this
action”) and 404 NOT_FOUND (“No supplier record for current user”). The
statuses haven’t changed. If your portal matched on FORBIDDEN or NOT_FOUND
for these causes, match on the new codes. See the
changelog.When access ends
The business ends a supplier’s access by removing theirSUPPLIER role in the
dashboard. Their next call is refused, and the code names the cause:
- No roles left. Every route answers
403 MEMBERSHIP_INACTIVE. - Some other role kept. The
codeisNO_SUPPLIER_ROLE. The status depends on the route and the role they kept:403where that role lacks the route’s permission,404where it has the permission but there is no supplier record to act on.
Alerts answer
404 to anyone who keeps any role, because every role holds
alert:readOwn. Rather than map statuses, call
the access route when a data route refuses: it gives the
same reasonCode with a 200.
Marking a supplier inactive does not end access to the data routes. An
inactive supplier isn’t offered in search, but keeps everything they had, on
your portal as on the dashboard. The access route reports them as
SUPPLIER_RECORD_INACTIVE, so you can decide what your portal does.
Removed, or never a supplier
The access route can’t say whether a person who now lacksSUPPLIER once had
it. Your server can, with the API key alone: GET /v1/projects/{projectId}/suppliers/{supplierId}
carries an access block.
Removing
SUPPLIER unlinks the record: userId becomes null,
invitationStatus becomes NONE and roles becomes [], whatever roles the
person keeps. accessEndedAt is what tells a removed supplier from one who was
never invited:
If your app reads a supplier’s data with the API key, rather than through the
supplier plane, decide access from this read:
The API key decides who sees what on a key-only read: MarketBox never learns
which person is behind the request.
roles also tells your key which suppliers
are staff. Keep the response on your server, as you would the supplier’s
email and phone.
Links in MarketBox emails
By default, the emails MarketBox sends to suppliers link to the MarketBox dashboard. When the project has a supplier portal URL, the supplier emails below link to your portal instead. A project admin sets it in the dashboard, under Settings › Notifications › Supplier portal. It can’t be set through the API. MarketBox adds two things to the URL at send time, and nothing else:bookingId. When an email is about exactly one booking for the supplier receiving it, it is added as a query parameter. A URL that already has a query string keeps it. An email about several bookings, or a day’s agenda, gets nobookingId: link that to the schedule.{supplierLocale}is replaced with the supplier’s locale: theirdefaultLocale, else their firstlocalesentry, else the project’sdefaultLocale, elseen-CA.
https (http only for localhost and 127.0.0.1), at most
2,048 characters, with no # fragment, no username or password, and no token
other than {supplierLocale}.
For example, take a portal URL ending in /{supplierLocale}/schedule and a
supplier whose locale is fr-CA. An email about one booking links to the URL
ending in /fr-CA/schedule?bookingId=bk_01kx16f2a0e5x9jv6r0c1qs7pm.
A supplier taken off a booking gets no
bookingId, because the plane returns a
booking only to its current supplier. Client emails and staff copies are
unchanged. See Emails.