> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Every request carries a Bearer API key. The key selects the environment and carries the scopes your app holds.

Every request to the Developer API carries a `Bearer` API key in the `Authorization` header:

```bash
# Sandbox
curl https://api.staging.maple.inc/v1/me \
  -H "Authorization: Bearer mpk_test_..."
```

A key answers three questions at once: **which app** you are, **which environment** you belong to (sandbox or production), and **which scopes** you hold. Verify any key with `GET /v1/me`, which returns exactly that.

Each environment has its own base URL — `https://api.staging.maple.inc/v1` for the sandbox and `https://api.maple.inc/v1` for production. Use the key that matches the host. See [Environments](https://docs.maple.inc/developer-api/concepts/environments.md).

## API keys

Maple approves your app and its scope ceiling. Invited organization members create and revoke keys in **Developers → your app → Overview & keys**. Sign in to the dashboard for the key’s environment (`https://app.staging.maple.inc` for sandbox keys, `https://app.maple.inc` for production keys); no merchant or restaurant selection is required.

| Key          | Environment | Base URL                           |
| ------------ | ----------- | ---------------------------------- |
| `mpk_test_…` | Sandbox     | `https://api.staging.maple.inc/v1` |
| `mpk_live_…` | Production  | `https://api.maple.inc/v1`         |

Send the key as the bearer token on every request, against the base URL for its environment. Keep keys server-side; never embed them in a client app or commit them to source control. Narrowing an app’s scopes takes effect immediately for its existing keys.

> [!WARNING]
>
> **The full key is shown once.** Save it in your secret manager before dismissing the creation dialog. Listing keys shows metadata and the last four characters, not a recoverable secret. Keep keys out of logs, screenshots, and support messages.

To replace a key, create a new one, update your client, verify it works, and explicitly revoke the old key. Revocation immediately stops authentication with that key. A suspended or revoked app cannot authenticate with any of its keys, although console access still supports inspection and protective revocation.

A key does **not** grant location access, create a sandbox, or approve production use. Maple manages app ownership, scope ceilings, location grants, and production approval separately. Staff access alone does not grant access to an unlinked app in the developer console.

Follow the [Quickstart](https://docs.maple.inc/developer-api/quickstart.md) to create a key and verify the returned app/environment with `/v1/me`.

## Scopes

Access is scoped, so your app holds only the permissions it needs:

| Scope                                          | Grants                                                                                                   |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `locations:read`                               | List and read granted locations                                                                          |
| `connections:read` / `connections:write`       | Read or manage the location connection                                                                   |
| `orders:read` / `orders:write`                 | Read orders or submit order decisions                                                                    |
| `menus:read` / `menus:write`                   | Read or publish a location’s menu                                                                        |
| `delivery_zones:read` / `delivery_zones:write` | Read or manage a connected location’s delivery zones and check deliverability                            |
| `webhooks:read` / `webhooks:write`             | Read or manage webhook subscriptions                                                                     |
| `bookings:read`                                | Read bookings, profile, availability, configuration, and live floor at granted locations                 |
| `bookings:write`                               | Hold slots and create, change, or cancel bookings for guests                                             |
| `bookings:manage`                              | Act for the venue: confirm, decline, seat, complete, cancel, or mark bookings no-show, and seat walk-ins |
| `bookings:configure`                           | Publish native booking configuration                                                                     |

A request missing a required scope returns `403` with code `insufficient_scope`. A key used against the wrong environment returns `403` with code `wrong_environment`. See [Errors](https://docs.maple.inc/developer-api/concepts/errors.md).

> [!TIP]
>
> Check what a key can do without making a real call: `GET /v1/me` returns the app, its environment, and its effective scopes.

## OAuth

> [!NOTE]
>
> **Under construction.** OAuth-based access (merchant-delegated tokens and `client_credentials` grants) is not part of the generally available Developer API yet. Use API keys for now. If your integration needs OAuth, talk to the Maple team — this section will expand when the flow is finalized.