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

# End-user authentication

> How signed-in clients and suppliers call the API through your backend, and who may call each end-user route.

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

## Two credentials

Every request to an end-user route carries **two** credentials, each with a
distinct job:

| Credential | Header | Identifies | Used for |
| - | - | - | - |
| Application | `x-api-key` | Your application and its project scope | Every API call |
| End user | `Authorization: Bearer <jwt>` | The signed-in person | End-user routes only |

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

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

| Plane | Routes | Acts as | Guide |
| - | - | - | - |
| Client | `/v1/projects/{projectId}/clients/me` and below | The client the token belongs to | [Build a booking flow](https://docs.gomarketbox.com/guides/booking-flow-auth.md) |
| Supplier | `/v1/projects/{projectId}/suppliers/me` and below | The supplier the token belongs to | [Build a supplier portal](https://docs.gomarketbox.com/guides/build-a-supplier-portal.md) |

## The golden rule

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

```
Browser                Your backend (BFF)          MarketBox API
  |   GET /bff/credits   |                                                    |
  |  + Bearer <jwt>  --> |                                                    |
  |                      |  GET /v1/projects/{projectId}/clients/me/credits   |
  |                      |  x-api-key: <secret>                        -->   |
  |                      |  Authorization: Bearer <jwt>                      |
  |  <-- 200 { data }    |  <-- 200 { 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.

> [!WARNING]
>
> 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](https://docs.gomarketbox.com/guides/booking-flow-auth.md) 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.

| Status and `code` | What it means |
| - | - |
| `401` | No token, a malformed `Authorization` header, or a token that is invalid or expired. Sign in again. |
| `401 UNAUTHORIZED` | `"Missing user token"`: the token is valid but carries no `sub` claim — usually an ID token or a machine token forwarded by mistake. Forward the person's access token. |
| `401 UNAUTHORIZED` | `"API key not provided"` or `"A publishable key cannot be used as an API key"`: your backend sent no API key, or sent the beacon's publishable key. Fix the backend, not the session. |
| `403 FORBIDDEN` | `"API key not recognized"`: the API key isn't one MarketBox knows. |
| `403 CAPABILITY_NOT_GRANTED` | The API key lacks Standard API access. |
| `403 FORBIDDEN` | `"User account not found. Complete registration first."`: the token is valid, but the person never finished signing up. Send them back through sign-up. |
| `403 FORBIDDEN` | The key can't access this project. On the client plane, also: the person has no `ACTIVE` membership (`"No active membership on this project"`), or their roles lack the permission (`"Insufficient permissions for this action"`). |
| `403 NOT_A_MEMBER`, `MEMBERSHIP_INACTIVE`, `NO_SUPPLIER_ROLE` | Supplier plane only: the person has no membership, their membership ended, or the roles they act under lack the permission. A supplier who hasn't accepted the business's invitation yet gets `NOT_A_MEMBER`. See [Supplier portal: refusals](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#refusals). |
| `403 ACTING_ROLE_NOT_HELD` | The request sent an `X-MB-Acting-Role` header naming a role the person doesn't hold. You don't need that header. |
| `404 NOT_FOUND` | Client plane: the person passed every check but has no client profile in this project. |
| `404 NO_SUPPLIER_ROLE`, `SUPPLIER_NOT_LINKED` | Supplier plane: the person passed every check but has no supplier record to act on. They act under no `SUPPLIER` role, or no supplier record is linked to their sign-in. |

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](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#check-access-first).

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


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