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

# Quickstart

> Sign in to the developer console, create your own key, and verify API requests and signed webhooks.

Use the developer console to manage credentials and webhooks for an app Maple has approved. Start in the sandbox and complete a supported business workflow before requesting production access.

## Before you begin

You need an invitation to a developer organization, an approved app assigned to that organization, and the dashboard for the environment you will use: `https://app.staging.maple.inc` for the sandbox or `https://app.maple.inc` for production (see [Environments](https://docs.maple.inc/developer-api/concepts/environments.md)). Maple prepares your sandbox and grants the locations your integration needs. **Creating a key does not create a sandbox or grant location access.**

If you do not have an invitation or approved app, [contact Maple](https://maple.inc/get-started). Public signup, app approval, location grants, and production activation are not self-service.

## Start with a coding agent

If a coding agent (Claude Code, Cursor, Codex, or similar) is building your integration, copy this prompt into it once you have a sandbox key in `MAPLE_KEY`. It points the agent at these docs and the API reference, keeps it in the sandbox, and tells it how to report anything in the API that gets in its way.

> Set up a coding agent to build against the Maple Developer API in the sandbox.
>
> You are building an integration with the Maple Developer API in this repository.
>
> Read these first:
>
> - The docs index: <https://docs.maple.inc/llms.txt>
> - The quickstart: <https://docs.maple.inc/developer-api/quickstart>
> - The OpenAPI spec, which is the source of truth for every endpoint and field: <https://docs.maple.inc/openapi/developer-api.json>
>
> Rules:
>
> - Use the sandbox only. The base URL is `https://api.staging.maple.inc/v1`, and the key is in the `MAPLE_KEY` environment variable (it starts with `mpk_test_`). Never print, log, or commit the key, and ask me before doing anything against production.
> - Send the key as `Authorization: Bearer $MAPLE_KEY`. Start by calling `GET /me` to confirm the app, the environment, and the scopes the key has, and plan around those scopes.
> - Keep the `x-request-id` header from every response. It identifies the request in the developer console and in feedback.
> - Branch on an error’s `_tag` and `code`, never its `message`. Follow `Retry-After` on a 429.
> - Verify the HMAC signature on every webhook before acting on it.
>
> When the API gets in your way (a bug, a capability you need that is missing, docs that disagree with what the API does, or an error that does not tell you what to change), report it with `POST /v1/feedback`, citing the `x-request-id` values involved, then carry on with the best workaround you have. See <https://docs.maple.inc/developer-api/concepts/feedback> for the fields.
>
> Start by reading the docs above, calling `GET /me`, and telling me what the key can do and which guide fits what we are building.

1. ### Sign in and select your app

   Follow your invitation, sign in with the invited email, and open **Developers**. Select the correct organization and approved app. You do not need to create or select a restaurant.

   Check the **Sandbox** or **Production** badge and API base URL before continuing. Each dashboard manages only its own deployment. Use the corresponding invitation/dashboard URL when switching environments; do not assume a shared session or shared data.

   If no app appears, ask Maple to approve or link it to the selected organization. Staff access alone does not make an app available in the developer console.

2. ### Create and save a key

   In **Overview & keys**, choose **Create key**, give it a name, and select only the approved scopes your client needs. Save the full key securely: it is shown once and cannot be retrieved after closing the dialog.

   Set `MAPLE_KEY` in your own client environment. The examples use that variable; do not paste a key into documentation, source control, screenshots, or request-history fields.

   Set the public base URL shown by your sandbox console:

   ```bash
   export MAPLE_BASE="https://api.staging.maple.inc/v1"
   ```

   A suspended or revoked app cannot authenticate with its keys. You can still inspect and revoke keys in the console.

3. ### Verify your identity

   Run the copied **/me** command from **Getting started**, or use:

   ```bash
   curl --include "$MAPLE_BASE/me" \
     -H "Authorization: Bearer $MAPLE_KEY"
   ```

   ```json
   {
     "object": "developer_app",
     "id": "dap_...",
     "name": "Your Integration",
     "environment": "test",
     "scopes": ["locations:read", "webhooks:read", "webhooks:write"]
   }
   ```

   Confirm the app, environment, and effective scopes. Keep the **`x-request-id`** response header to locate this call in **Requests**. A key’s permissions never exceed the app’s current approved scope ceiling.

4. ### Inspect your locations

   **Granted locations** shows the grants configured for this app. To read locations through the API, use a key with `locations:read`:

   ```bash
   curl --include "$MAPLE_BASE/locations" \
     -H "Authorization: Bearer $MAPLE_KEY"
   ```

   An empty list is not a request to create a restaurant in the portal. Ask Maple to provide the test location and grant your integration needs.

   A grant and an order-receiver connection are different. For an order/POS integration, follow [Receive and decide orders](https://docs.maple.inc/developer-api/guides/receive-orders.md) to connect the granted location. For reservations, read the [booking profile and booking guide](https://docs.maple.inc/developer-api/guides/take-bookings.md); do not create an order-receiver connection just to test bookings.

5. ### Register and test a webhook

   Open **Webhooks → Endpoints**, choose **Add endpoint**, enter a public HTTPS URL you control, and select supported event types. Your app needs `webhooks:read` to inspect this area and `webhooks:write` to change endpoints or send tests.

   Save the one-time signing secret and implement [signature verification](https://docs.maple.inc/developer-api/concepts/webhooks.md#verifying-the-signature) in your receiver. Creating an endpoint does not send a test automatically.

   Choose **Send test**. A delivered result means the receiver returned a `2xx`; it does not prove your handler verified the signature. Failed or skipped tests are not success. A test is one attempt, with no automatic retry scheduled by the action.

6. ### Find the request and delivery

   In **Requests**, search for the `x-request-id` from your API call. Inspect its status and safe error summary without needing access to internal logs. History covers requests made with your app’s keys or tokens, including revoked ones, and is kept for 7 days; requests without a recognized credential are not recorded. An unavailable history service is not an empty successful history.

   In **Webhooks → Deliveries**, inspect the signed test’s outcome, attempt count, HTTP status, and timestamps. The history is an aggregate per event/endpoint, not a per-attempt timeline. URLs and enabled state describe current endpoint configuration, not the destination of a past request.

   For a replayable business event, **Review event** previews an event-level retry. Confirm it to retry eligible destinations; successful pairs and disabled destinations are skipped. Test-only rows offer **Send another test**, not replay of a nonexistent event-log entry. See [Webhooks](https://docs.maple.inc/developer-api/concepts/webhooks.md#manage-deliveries-in-the-console) for limits and uncertain outcomes.

   **Check recent activity** in Getting started reads recent `/me` and delivered-test metadata on demand. It is a setup hint, not proof that your current key, current endpoint configuration, or complete integration is verified.

7. ### Complete your business workflow and verify revocation

   Use the guide for your approved integration to exercise a real operation against your isolated test location—for example, availability → hold → create → change/cancel a reservation. Receive the resulting business event and find its diagnostics. `/me` and a synthetic test alone do not verify the business integration.

   When the temporary acceptance key is no longer needed, choose **Revoke** in the console and confirm. Repeat the `/me` request with that key and verify authentication fails. Do not revoke a key still used by another client.

## If you get stuck

| What you see                        | What to check                                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| No approved apps                    | Invited email, selected organization, and Maple’s app ownership/approval                                            |
| No grants or an empty location list | Environment-scoped location grants and `locations:read` on the key                                                  |
| No recent requests                  | Your response/request ID, filters, the 7-day retention, and that you called with a key for this app and environment |
| History unavailable                 | Retry the history read later; key and webhook management are separate                                               |
| Disabled endpoint                   | Inspect its configuration and failure history before re-enabling                                                    |
| Suspended app                       | Contact Maple; creating another key does not bypass app status                                                      |
| Wrong environment                   | Match dashboard, API base URL, and credential; sandbox does not activate production                                 |

## Continue with your integration

- [Take bookings](https://docs.maple.inc/developer-api/guides/take-bookings.md): Read the booking profile, search availability, hold a slot, and create or change reservations.
- [Receive and decide orders](https://docs.maple.inc/developer-api/guides/receive-orders.md): Connect a granted location and handle order notifications and decisions.
- [Publish a menu](https://docs.maple.inc/developer-api/guides/publish-menu.md): Publish the catalog for an approved order/POS integration.
- [Production access](https://docs.maple.inc/developer-api/concepts/environments.md): Review the separate approval, credentials, grants, and endpoint setup needed to go live.