> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Supplier portal: sign-in and access

> What a supplier portal needs before its first call, the two credentials on every supplier-plane request, checking access on sign-in, every refusal and its code, telling a removed supplier from one never invited, and where MarketBox emails send suppliers.

This page is part of [Build a supplier portal](https://docs.gomarketbox.com/guides/build-a-supplier-portal.md).
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](https://docs.gomarketbox.com/guides/booking-flow-auth.md).

## 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](https://docs.gomarketbox.com/concepts/authentication.md#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:

| Header | What it is |
| - | - |
| `x-api-key` | Your Application's API key. Your BFF adds it; the browser never holds it. |
| `Authorization: Bearer <accessToken>` | The signed-in supplier's **access token** from your own sign-in. |

**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.

> [!WARNING]
>
> 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](https://docs.gomarketbox.com/concepts/end-user-authentication.md).

## 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:

| Area | Permission |
| - | - |
| Profile and photo, hours, blocked time, travel zones, venues | `supplier:manageOwn` |
| Bookings, attendance reports, cancel and reschedule | `booking:readOwn` |
| Demand and search insights | `insights:readOwn` |
| Alerts | `alert:readOwn` (every role holds it) |

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.

```bash theme={null}
curl "$MARKETBOX_API_URL/v1/projects/$MARKETBOX_PROJECT_ID/suppliers/me/access" \
  -H "x-api-key: $MARKETBOX_API_KEY" \
  -H "Authorization: Bearer <accessToken>"
```

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:

```json theme={null}
{
  "data": {
    "allowed": true,
    "reasonCode": "SUPPLIER_ACTIVE",
    "message": "You have supplier access on this project.",
    "supplierId": "sup_01kv60qgnef2kt3pvqgwmkbzfr",
    "roles": ["SUPPLIER"],
    "membershipStatus": "ACTIVE"
  }
}
```

A person whose `SUPPLIER` role was removed, and who kept `CLIENT`, gets this:

```json theme={null}
{
  "data": {
    "allowed": false,
    "reasonCode": "NO_SUPPLIER_ROLE",
    "message": "You don't have supplier access on this project.",
    "supplierId": null,
    "roles": ["CLIENT"],
    "membershipStatus": "ACTIVE"
  }
}
```

| Field | What it holds |
| - | - |
| `allowed` | `true` only for `SUPPLIER_ACTIVE`. Use the plane only when it is `true`. |
| `reasonCode` | Why. One of the seven codes below. Branch on this. |
| `message` | The reason, written for the person. Show it when `allowed` is `false`. |
| `supplierId` | The supplier record linked to the person, for `SUPPLIER_ACTIVE` and `SUPPLIER_RECORD_INACTIVE`. Otherwise `null`. |
| `roles` | Every role the person holds on the project, in the order `CLIENT`, `ADMIN`, `MANAGER`, `DEVELOPER`, `SUPPLIER`. `[]` unless the membership is `ACTIVE`. |
| `membershipStatus` | `ACTIVE`, `INACTIVE`, or `null` when the person has no account or no membership here. |

| `reasonCode` | When | `allowed` | `message` |
| - | - | - | - |
| `SUPPLIER_ACTIVE` | An `ACTIVE` membership with `SUPPLIER`, and a linked, active supplier record. | `true` | "You have supplier access on this project." |
| `SUPPLIER_RECORD_INACTIVE` | As above, but the supplier record is marked inactive (`active: false`). | `false` | "Your supplier profile on this project is inactive." |
| `NO_ACCOUNT` | The token is valid but names no MarketBox account. | `false` | "There is no MarketBox account for this sign-in. Complete registration first." |
| `NOT_A_MEMBER` | No membership of this project. An invited supplier who hasn't accepted yet, and has no other role here, gets this. | `false` | "You are not a member of this project." |
| `MEMBERSHIP_INACTIVE` | The membership has ended: every role was removed. | `false` | "Your access to this project has ended." |
| `NO_SUPPLIER_ROLE` | An `ACTIVE` membership without `SUPPLIER`: it was removed, or they never had it. | `false` | "You don't have supplier access on this project." |
| `SUPPLIER_NOT_LINKED` | Holds `SUPPLIER`, but no single supplier record is linked to the person. | `false` | "Your sign-in isn't linked to a supplier record on this project." |

`SUPPLIER_RECORD_INACTIVE` is your call. The data routes still serve an
inactive supplier (see [When access ends](#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](#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](https://docs.gomarketbox.com/concepts/errors.md). **Branch on
`code`, not on the status.** The same cause can come back as `403` on one route
and `404` on another.

| Status and `code` | What it means |
| - | - |
| `401 UNAUTHORIZED` | "API key not provided", or "A publishable key cannot be used as an API key". Your BFF sent no key, or a publishable one. Fix the BFF; don't sign the supplier out. |
| `403 FORBIDDEN` | "API key not recognized". The `x-api-key` value isn't a MarketBox API key. |
| `403 CAPABILITY_NOT_GRANTED` | Your API key lacks Standard API access. Checked before the token. |
| `401 HTTP_ERROR` | No token, a malformed `Authorization` header, or a token that is invalid or expired. |
| `401 UNAUTHORIZED` | A token that names no user — and, once enforced, a token from another client. |
| `403 FORBIDDEN` | "User account not found. Complete registration first." The token is valid, but the person hasn't finished signing up to MarketBox. The access route reports this as `NO_ACCOUNT`. |
| `403 FORBIDDEN` | The key can't use this project. |
| `403 NOT_A_MEMBER` | "You are not a member of this project." The person has no membership of the project at all — for example, an invited supplier who hasn't accepted yet. |
| `403 MEMBERSHIP_INACTIVE` | "Your access to this project has ended." They had a membership, and every role was removed. |
| `403 NO_SUPPLIER_ROLE` | "You don't have supplier access on this project." They are an `ACTIVE` member, but none of the roles they act under grants the route's permission. Their `SUPPLIER` role was removed, or they never had it. |
| `403 ACTING_ROLE_NOT_HELD` | Your request sent `X-MB-Acting-Role` naming a role the person doesn't hold. A portal doesn't need that header. |
| `404 NOT_FOUND` | No such project. |
| `404 NO_SUPPLIER_ROLE` | "You don't have supplier access on this project." The route's permission passed — an admin or manager, or anyone on the bookings and alerts routes — but the person acts under no `SUPPLIER` role, so there is no supplier record to act on. |
| `404 SUPPLIER_NOT_LINKED` | "Your sign-in isn't linked to a supplier record on this project." They hold `SUPPLIER`, but no single supplier record in this project is linked to their sign-in. |

A person whose access ended sees this:

```json theme={null}
{
  "code": "MEMBERSHIP_INACTIVE",
  "message": "Your access to this project has ended.",
  "statusCode": 403,
  "requestId": "4b1d7e2a-9c3f-4a58-b6e0-2f8d1c5a7e93"
}
```

A person whose `SUPPLIER` role was removed, and who kept `CLIENT`, sees this on
`GET /suppliers/me/bookings`:

```json theme={null}
{
  "code": "NO_SUPPLIER_ROLE",
  "message": "You don't have supplier access on this project.",
  "statusCode": 404,
  "requestId": "8e2c5a17-3d9b-4f60-a1c4-7b6e0d2f9a35"
}
```

> [!NOTE]
>
> 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](https://docs.gomarketbox.com/changelog/overview.md).

## 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.

| Role kept | `403 NO_SUPPLIER_ROLE` on | `404 NO_SUPPLIER_ROLE` on |
| - | - | - |
| `CLIENT` | Profile and photo, hours, blocked time, travel zones, venues, demand and search insights | Bookings, alerts |
| `ADMIN` | — | Every route |
| `MANAGER` | Demand and search insights | Every other route |
| `DEVELOPER` | Every route but alerts | Alerts |

Alerts answer `404` to anyone who keeps any role, because every role holds
`alert:readOwn`. Rather than map statuses, call
[the access route](#check-access-first) 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.

```json theme={null}
"access": {
  "userId": null,
  "invitationStatus": "NONE",
  "roles": [],
  "membershipStatus": null,
  "accessEndedAt": "2026-11-12T15:04:22.000Z"
}
```

| Field | Meaning |
| - | - |
| `userId` | The MarketBox user linked to the record, or `null` when no one is linked. It is the user `/suppliers/me` resolves that person's token to. |
| `invitationStatus` | `NONE` (never invited, or unlinked since), `INVITED` (invited, not yet accepted) or `LINKED` (a person accepted). |
| `roles` | Every role the linked person holds on the project, in the order `CLIENT`, `ADMIN`, `MANAGER`, `DEVELOPER`, `SUPPLIER`. `[]` when the record isn't linked, or the membership isn't `ACTIVE`. |
| `membershipStatus` | The linked person's membership: `ACTIVE` or `INACTIVE`. `null` when the record isn't linked. |
| `accessEndedAt` | When the record was last unlinked from a person (ISO 8601, UTC), or `null`. Cleared when someone accepts a new invitation. |

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:

| Situation | `invitationStatus` | `userId` | `roles` | `membershipStatus` | `accessEndedAt` |
| - | - | - | - | - | - |
| Never invited | `NONE` | `null` | `[]` | `null` | `null` |
| Invited, not yet accepted | `INVITED` | `null` | `[]` | `null` | `null` |
| Linked | `LINKED` | set | includes `SUPPLIER` | `ACTIVE` | `null` |
| `SUPPLIER` removed | `NONE` | `null` | `[]` | `null` | set |
| Removed, then invited again | `INVITED` | `null` | `[]` | `null` | set |
| Removed, invited again and accepted | `LINKED` | set | includes `SUPPLIER` | `ACTIVE` | `null` |

If your app reads a supplier's data with the API key, rather than through the
supplier plane, decide access from this read:

| `GET /suppliers/{supplierId}` says | What it means | What your app does |
| - | - | - |
| `404`, or `active: false` | The record was deleted, or the business paused the supplier. | Treat the supplier as removed. |
| `access.roles` includes `SUPPLIER` | A current, linked supplier. | Move them to the supplier plane: sign them in and [check access](#check-access-first). |
| No link, `accessEndedAt` set | The supplier was removed. | End their supplier session in your app. Leave any other sign-in the person has alone. |
| No link, `accessEndedAt` `null` | The supplier never joined. | Keep whatever limited view your app gives a supplier who hasn't been invited yet. |

> [!WARNING]
>
> `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`.

## 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 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`.

| Email | With a portal URL |
| - | - |
| New booking | Your portal; `bookingId` when the email covers exactly one booking. |
| Booking updated, to the current supplier | Your portal, with `bookingId`. |
| Booking updated, to the previously assigned supplier | Your portal, without `bookingId`. |
| Booking cancelled, to the supplier | Your portal, with `bookingId`. |
| Booking cancelled, to the previously assigned supplier | Your portal, without `bookingId`. |
| Order cancelled, to the supplier | Your portal; `bookingId` when the email covers exactly one booking. |
| Daily agenda | Your portal. |
| Rate your client, and its follow-ups | Unchanged: the project's review URL, or MarketBox's review page. |
| Invitation | Unchanged: the dashboard. |

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](https://docs.gomarketbox.com/concepts/emails.md#links-in-supplier-emails).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.