Skip to main content
This guide walks you through building a custom booking flow that signs users in and calls the MarketBox API on their behalf. It covers both auth planes, the backend-for-frontend (BFF) pattern, client onboarding, reading a user’s package credits, and letting them book their own credit. If you haven’t yet, read End-user authentication first — it explains the two-plane model this guide builds on. For the whole checkout on one page, from sign-in to the confirmation screen, see Client checkout, end to end. For the client’s account page, see Manage a client’s account.

Prerequisites: create an Application

In the project’s API Access page in the MarketBox dashboard, a project admin creates an Application. An Application is the container for one integration (for example, your booking website): it groups the OAuth client your users sign in through and the API key your backend calls with. Creating an Application issues two things:
  • A clientId — identifies your OAuth client. Safe to expose in browser config.
  • A one-time API key — shown once, in the “Application created” dialog. Copy it now; it cannot be retrieved later. This is the server-only secret from Authentication. It needs Standard API access, the default; a key without it is refused with 403 CAPABILITY_NOT_GRANTED. See Capabilities.
The dialog also shows a Connection details block of per-environment constants. The same block is available any time on the Connection details panel of the API Access page.

Values you receive

Per-application (from creating the Application): Per-environment Connection details (shared across all Applications):
These are standard OIDC values. MarketBox lists the endpoints explicitly rather than relying on OIDC discovery, because the discovery document does not advertise the hosted-login endpoints or a logout endpoint. Copy them directly from the Connection details panel.

Wire hosted-login auth (PKCE)

Sign-in uses the OAuth 2.0 Authorization Code flow with PKCE. Your browser redirects to MarketBox hosted login; after the user authenticates, MarketBox redirects back to your callback URL with an authorization code, which you exchange for tokens.
1

Allow-list your redirect URLs

In the dashboard, on your Application’s settings, add:
  • Callback URL: https://example.com/auth/callback (the page that handles the code exchange, replacing example.com with your own domain)
  • Logout URL: https://example.com (where the user lands after sign-out)
For local development also add http://localhost:4000/auth/callback and http://localhost:4000.
The registered logout URL must exactly match the logout_uri your app sends — the bare origin with no trailing slash. The match is an exact string comparison.
2

Configure the OAuth client

The env-var mapping from Connection details is direct — no derivation needed:The example below uses oidc-client-ts in a Next.js app, but any OIDC/PKCE client works.
3

Send the user to sign in

4

Handle the callback

On your /auth/callback page, complete the PKCE code exchange and read the access token:
Forward the access token, not the ID token. It must come from your own Application’s clientId: a token issued to another client — the MarketBox dashboard’s or another Application’s — is logged today and will be refused with 401 once enforcement is switched on. See End-user authentication.Call your backend to onboard the user immediately after the first sign-in (see Onboard the client).
5

Sign out

The logout endpoint takes client_id + logout_uri rather than standard RP-initiated logout, so clear the local session and redirect manually:

The BFF pattern

Your backend-for-frontend (BFF) is the only place that holds the API key. Browser pages call BFF routes; BFF routes attach the key before calling the MarketBox API.
The browser calls /api/bff/credits with only Authorization: Bearer <token>. It never touches MARKETBOX_API_KEY.
Hardening. The example above has the browser hold the token in memory and send it to the BFF on each request. A more hardened variant stores the token in an httpOnly cookie session managed entirely by the BFF: after the code exchange the BFF sets a signed cookie, and subsequent requests read the token from the cookie rather than a request header. This removes the token from browser memory and from network headers visible in DevTools.

Onboard the client

Call POST /v1/projects/{projectId}/clients/me once after the user’s first authenticated sign-in. It is idempotent: 201 the first time, 200 on every later call, so it’s safe to call on every callback. On the first call it provisions the signed-in user as a client of the project — an ACTIVE project membership with the CLIENT role and a client profile, plus a Stripe Connect stripeCustomerId on that profile when the project has payments configured. A person who is already a member of the project, such as an admin or a supplier, and signs in on your booking site becomes a client too. Onboarding adds CLIENT to their roles and keeps the others. Every other /clients/me route requires that ACTIVE membership. See Who may call an end-user route. If the business has removed the person’s access, onboarding refuses them, and nothing is read or linked:

Send the name your checkout collected

The body is optional. Send firstName, lastName and phone when your checkout collected them:
Without names, the client is recorded under the names from their sign-in. A Google sign-in supplies real names. An email-and-password sign-up supplies only the email address, so the business would see the client as the part of it before the @ on orders, bookings and emails. Each field you send overwrites the stored value on every call, including for a client who is already onboarded, and is copied to the client’s record in Stripe. A blank or null field counts as not sent and never clears a stored value. Names are trimmed and must be at most 80 characters. The phone is stored in E.164 form (+14165550134). An invalid name or phone is a 400, and nothing is written. The name is the client’s record in this project only. It does not rename the person’s MarketBox account.

Change the name or phone later

PATCH /v1/projects/{projectId}/clients/me changes the signed-in client’s firstName, lastName or phone. It takes the same two credentials as onboarding, and the client must already be onboarded, or it is a 404.
  • Send only the fields to change. A body with nothing to update is a 400.
  • Names are 1–80 characters after trimming. They can be changed but not cleared, so a blank or null name is a 400.
  • Send phone: null to clear the phone.
Call it before POST /orders, so booking and order emails use the new name. The change is also copied to the client’s record in Stripe. If that copy fails, the profile is still updated and the call still returns 200. The response is the whole profile, with its saved addresses. Call it immediately after the code exchange succeeds, before redirecting into your app:
The BFF route forwards this to POST /v1/projects/{projectId}/clients/me with both the API key and the bearer token.

Returning visits: fetch credits

On authenticated pages, call your BFF to get the user’s remaining package credits:
The BFF calls GET /v1/projects/{projectId}/clients/me/credits. Each entry is a PACKAGE order item the client owns:
  • quantityRemaining is the live balance: the sessions the client can still book.
  • quantityReturned counts the sessions cancellations have returned to this credit, ever. They are already counted in quantityRemaining, so don’t add them. A returned session may have been booked again since. Use it to say “1 session was returned to your package”, not to work out a balance.
Only credits on PAID orders are listed. A credit that is used up, has expired or was removed is left out. Pass includeExpired=true to keep the expired ones.

Book a client’s own credit

The signed-in client can book sessions from their own credit:
It takes the same two credentials as the other /clients/me routes, and the bookings record the client as the person who made them. For the whole flow — planning a slate from the credit, booking it, and the refusals this route adds — see Book a client’s package credit.

Reference

Connection constants

Copy these from the Connection details panel in the dashboard (API Access page). They are per-environment, not per-application.

Endpoints used in this guide

Error and status cases

Security checklist

MARKETBOX_API_KEY is in a server-only env var — no NEXT_PUBLIC_ prefix.
MARKETBOX_API_URL (for BFF use) is server-only — the browser never sees it.
Callback and logout URLs are allow-listed in the Application settings.
The BFF validates that the incoming Authorization header starts with Bearer before forwarding it.
The one-time API key was copied at creation time and stored in a secrets manager — never committed to source control.

Run the sample app

A runnable Next.js reference implementation is available on GitHub: pajawale/sample-booking-flow. It demonstrates:
  • PKCE sign-in / sign-up / sign-out against MarketBox hosted login
  • A callback page that onboards the client
  • A credits page served through the BFF
Follow the repo’s README to configure the Connection details and run it locally on port 4000.