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

# Projects and scope

> How the API is organized around projects, and how scope shapes what a key can do.

Every resource in the MarketBox API lives inside a **project**. Bookings,
orders, offerings, and suppliers all carry a `projectId` and are listed,
created, and modified through paths scoped to it — for example:

```
/v1/projects/{projectId}/bookings
```

A project is the unit of isolation: data, configuration, and API key
authorization all line up at the project boundary.

## Why every path is project-scoped

Even read-only endpoints take a `{projectId}`. This is intentional:

* **Security** — your key's `projectScope` is checked against the
  `{projectId}` in the URL on every request, with no global fallback.
* **Cardinality** — listing across all projects would scan unbounded
  amounts of data. Project-scoped listing keeps every query bounded.
* **Multi-tenancy** — most businesses on MarketBox run multiple projects
  (per brand, per region, per environment). Forcing the `{projectId}`
  into the path keeps that explicit at every call site.

If you need to operate across projects, make N requests — one per project.
A wildcard-scoped key (`["*"]`) can hit any project the owning user has
access to, but the `{projectId}` is still required in the URL.

## How `tenantId` relates

The API key carries a `userId` (the human or service account that minted
it). On every write, MarketBox tags the record with `tenantId = userId`.

Project membership is a separate concept managed in the dashboard:
"who owns / collaborates on this project." The API key inherits its
allowed projects from the owning user's membership — narrowed further by
the key's `projectScope`.

Concretely:

```
api key  →  owning user  →  user's projects  →  key's projectScope
```

A scope check passes only if the project the key targets sits at the end
of that chain.

## Resolving project ids

Project ids are minted in the dashboard. You can also retrieve them via
the dashboard UI; a public API endpoint that lists projects is not part
of the open API surface — by design, projects are a control-plane
concept, not a data-plane one.

## What's not in a project

A handful of endpoints are unversioned and project-agnostic:

| Endpoint | Auth? | Purpose |
| - | - | - |
| `GET /health` | No | Liveness check for monitoring. |
| `GET /v1/openapi.json` | No | Machine-readable spec for codegen. |

Every other endpoint — for example `/v1/projects/{projectId}/bookings` —
requires a valid API key and a matching project scope. The one exception is
the browser beacon, `POST /v1/projects/{projectId}/events/beacon`: it takes a
publishable key that belongs to the project instead. See
[Report site events](https://docs.gomarketbox.com/guides/report-site-events.md#send-events-from-the-browser).


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