Skip to main content
This page is part of Build a supplier portal. Every supplier-plane route lives under /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 clientId for 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 ACTIVE membership with the SUPPLIER role, 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.
Today a token from another client is logged and the request still goes through. Once enforcement is switched on, the same request is a 401 UNAUTHORIZED. Send your own client’s access token now, and nothing changes for you when it is switched on.
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:
  1. Your API key, its capabilities and its project scope.
  2. The user token.
  3. The person’s membership of the project.
  4. Their supplier record in this project.
The membership is read on every request. A change the business makes in the dashboard applies to the supplier’s next call. The person must hold an 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.
Unlike the data routes, it answers 200 for every outcome about the person. One call tells your portal which screen to show. A current supplier gets this:
A person whose 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, with allowed: false. The data routes answer 200.
  • X-MB-Acting-Role. A data route judges the request on the role the header names. A person who holds SUPPLIER but sends X-MB-Acting-Role: CLIENT gets 404 NO_SUPPLIER_ROLE on 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 on code, 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:
A person whose 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 their SUPPLIER 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 code is NO_SUPPLIER_ROLE. The status depends on the route and the role they kept: 403 where that role lacks the route’s permission, 404 where 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 lacks SUPPLIER 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:
accessEndedAt is stamped from November 5, 2026 onward. A supplier removed before that has accessEndedAt: null, and looks the same as one who was never invited. To end such a supplier’s access in your app, ask the business to mark the record inactive.
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. 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 no bookingId: link that to the schedule.
  • {supplierLocale} is replaced with the supplier’s locale: their defaultLocale, else their first locales entry, else the project’s defaultLocale, else en-CA.
No project id, supplier id, email address or token is added. The link is only a pointer: your portal signs the supplier in and calls the supplier plane. The URL must be 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.