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.
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, replacingexample.comwith your own domain) - Logout URL:
https://example.com(where the user lands after sign-out)
http://localhost:4000/auth/callback and
http://localhost:4000.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 Forward the access token, not the ID token. It must come from your own
Application’s
/auth/callback page, complete the PKCE code exchange and read the
access token: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./api/bff/credits with only Authorization: Bearer <token>.
It never touches MARKETBOX_API_KEY.
Onboard the client
CallPOST /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. SendfirstName, lastName and phone when your
checkout collected them:
@ 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
nullname is a400. - Send
phone: nullto clear the phone.
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:
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:GET /v1/projects/{projectId}/clients/me/credits. Each entry is
a PACKAGE order item the client owns:
quantityRemainingis the live balance: the sessions the client can still book.quantityReturnedcounts the sessions cancellations have returned to this credit, ever. They are already counted inquantityRemaining, 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.
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:/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
README to configure the Connection details and run it
locally on port 4000.