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

# Authentication

> How API keys, project scope, and tenancy work.

The MarketBox API authenticates every request with an **API key** carried
in the `x-api-key` header. The key identifies *your application* and behaves
as a long-lived service credential, minted in the MarketBox dashboard.

Some routes also act on behalf of a *signed-in end user* and additionally
require a per-user token: the client's `/clients/me` routes and the supplier's
`/suppliers/me` routes. Those routes are the exception — most of the API
needs only the API key. See
[End-user authentication](https://docs.gomarketbox.com/concepts/end-user-authentication.md) for those planes
and when you need them.

One route takes a third credential: the browser beacon for site events,
`POST /v1/projects/{projectId}/events/beacon`, takes a **publishable key** in
its query string instead of an API key. See
[Report site events](https://docs.gomarketbox.com/guides/report-site-events.md#send-events-from-the-browser).

## The header

```http theme={null}
GET /v1/projects/prj_acme/bookings HTTP/1.1
Host: $MARKETBOX_API_URL
x-api-key: $MARKETBOX_API_KEY
```

The key value is an opaque string. It has no prefix, and nothing in it names
an environment or a project.

### When the key is missing or wrong

A request with no `x-api-key`, or one carrying a key MarketBox does not
recognise, is rejected **at the edge** with `403` — before any business logic
runs, and before your key's project scope is evaluated at all. It returns the
same error envelope as every other MarketBox error, so you can read `code` here
exactly as you do everywhere else:

```json theme={null}
{
  "code": "FORBIDDEN",
  "message": "API key missing or not recognised",
  "statusCode": 403,
  "requestId": "8f3c1a4e-2b7d-4f19-9a55-1c0e7d2b6f84"
}
```

A request to a path the API does not serve is rejected the same way and carries
the same `code`, with `"message": "No such route"`. The two are `403` for the
same reason — the edge refuses them before it knows anything about you — so the
`message` is what tells them apart.

> [!NOTE]
>
> Because these are rejected before your request reaches the application, the
> `requestId` here is the gateway's own id rather than an `X-Request-Id` you
> supplied. Quote it when contacting support; it is still the id that identifies
> your request in our logs.

## What a key carries

When you mint a key in the dashboard, MarketBox stores the following
metadata against it:

| Field | Meaning |
| - | - |
| `friendlyName` | Human-readable label, shown only in the dashboard. |
| `userId` | The MarketBox user who owns the key. Becomes the `tenantId` on writes, shared by every key that user owns. |
| `projectScope` | Which projects the key may act on. See below. |
| `capabilities` | Which kinds of route the key may call. See [Capabilities](#capabilities). |
| `createdAt` | When the key was minted. |
| `lastUsedAt` | Not updated after the key is created today. Don't use it to find idle keys. |

The raw key value is shown **once**, at create time. MarketBox stores only
the hash — if you lose it, you must mint a new one.

## Project scope

`projectScope` is an array of project ids that gates every authenticated
call. There are three meaningful shapes:

| Scope | Meaning |
| - | - |
| `["*"]` | Wildcard — every project the owning user has access to. |
| `["prj_01h2xcejqtfzcjxkvc4ay3pnh3"]` | Restricted — only that project. |
| `[]` | Kill switch — no access. Use to pause a key without deleting it. |

Mixing the wildcard with an explicit id (e.g. `["*", "prj_01h2xcejqtfzcjxkvc4ay3pnh3"]`) is
rejected at create time as malformed.

The wildcard expands **only within the owning user's blast radius** — it
never crosses users. A compromised wildcard key from one user can never
touch another user's projects.

## Scope enforcement

Every tenant-scoped endpoint has a `{projectId}` path parameter. On each
request, the API:

1. Validates the API key and resolves it to its scope.
2. Reads `{projectId}` from the URL.
3. Checks `scope.includes("*") || scope.includes(projectId)`.
4. Returns `403` if not allowed.

You'll get a `403` — not a `404` — if a project exists but your key isn't
scoped to it. A `404` means the project itself doesn't exist.

## Capabilities

Project scope says **which projects** a key may act on. Capabilities say **which
kinds of route** it may call. A project admin sets them on the Application, on
the **API Access** page of the dashboard:

| Capability | Dashboard label | What it allows |
| - | - | - |
| `*` | **Standard API access** | Every route in this API, including both end-user planes — except the site-events route. |
| `events:write` | **Site events** | `POST /v1/projects/{projectId}/events`. |
| `events:import` | **Historical event import** | Sending site events up to 400 days old (with `events:write`). |

Two rules to know:

* **`*` doesn't include the event capabilities.** A key reports site events
  only if `events:write` was granted by name. Without it, the events route
  answers `403 FORBIDDEN`.
* **A key without `*` can call nothing else.** A key with no capabilities
  ticked, or only **Site events**, is refused on every other route — before the
  project, the user token or any data is read.

A key minted before capabilities existed carries no list, and is treated as
`*`. It keeps working as before.

### When the key lacks Standard API access

```json theme={null}
{
  "code": "CAPABILITY_NOT_GRANTED",
  "message": "This API key has no capabilities, so it can call nothing on the open API. A project admin grants them on the dashboard's API Access screen.",
  "statusCode": 403,
  "requestId": "2d8f4b6a-3c1e-4f97-8a25-7e0b9c3d1f64"
}
```

A key that holds only some capabilities gets the same `code`, and a `message`
naming what it holds. To fix it, a project admin ticks **Standard API access**
on the Application. A key may hold `*` and `events:write` together.

## Test keys and sandbox

MarketBox has one kind of API key. There are no test keys, and there is no
sandbox.

* **Every key is live.** A key acts on the real data of its project. A booking
  you create claims the supplier's time, and MarketBox sends the
  [emails](https://docs.gomarketbox.com/concepts/emails.md) it sends for any booking.
* **Card payments are live too.** A card you charge through
  [Accept payments with Stripe](https://docs.gomarketbox.com/guides/accept-payments-with-stripe.md) is really
  charged. Stripe's test cards are declined.

To try the API without touching a live business, use a separate project. Each
project has its own services, suppliers, clients, bookings and orders, and a
key minted in one project can't read or write another. Create your test
services, suppliers and clients there, and use people and email addresses you
control.

## Rotating keys

To rotate:

1. Mint a new key with the same scope in the dashboard.
2. Roll out the new key to your callers.
3. Revoke the old key once traffic is fully off it.

Keys cannot be edited in place — name and scope are immutable after
creation. Rotation = mint + revoke.

## Tenancy

Every write (`POST`, `PATCH`, `DELETE`) is tagged with the API key's
owning `userId` as `tenantId` on the underlying record. `tenantId` names
the **user**, not the key: every key that user owns writes the same
`tenantId`, so it can't tell you which of them made a change. MarketBox
records the acting key separately, by its key id (`apiKeyId`), in its own
audit trail. That id isn't returned on records. To tell your own callers
apart, give each one its own key and log which key each call used.

You don't pass `tenantId` yourself — MarketBox derives it from the key on
the server.


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