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

> From a test API key to a verified webhook delivery in about ten minutes.

By the end of this page you'll have made your first authenticated call, listed the locations your app can reach, and received a real signed webhook at your own endpoint — all in test mode, against isolated data you can't break.

## Before you begin

You need a **sandbox API key** (`mpk_test_…`). The Maple team issues one when they create your developer app during onboarding. If you don't have one yet, [contact us](https://maple.inc/get-started) — it takes us a few minutes.

That's the only prerequisite. There's no SDK to install; every example here is plain `curl` you can paste into a terminal. You'll work against the **sandbox** the whole way — isolated data you can't break. (Production lives at `https://api.maple.inc/v1`; see [Environments](/developer-api/concepts/environments).)

<Tip>
  Keep your key and the sandbox base URL in environment variables so you can copy the examples verbatim:

  ```bash theme={null}
  export MAPLE_KEY="mpk_test_..."
  export MAPLE_BASE="https://api.staging.maple.inc/v1"
  ```
</Tip>

<Steps>
  <Step title="Confirm the API is reachable">
    `/ping` needs no credential. A clean response means your network can reach Maple.

    ```bash theme={null}
    curl $MAPLE_BASE/ping
    ```

    ```json Response theme={null}
    { "object": "developer_api_status", "status": "ok", "version": "..." }
    ```
  </Step>

  <Step title="Make your first authenticated call">
    `GET /v1/me` echoes back the app your credential belongs to, the environment it operates in, and the scopes it holds. It's the fastest way to confirm a key works.

    ```bash theme={null}
    curl $MAPLE_BASE/me \
      -H "Authorization: Bearer $MAPLE_KEY"
    ```

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

    <Check>
      `environment` reads `test`. A test key can only ever see test data — nothing you do here touches a live merchant.
    </Check>

    If you get a `401`, the key is missing, malformed, or inactive. See [Errors](/developer-api/concepts/errors).
  </Step>

  <Step title="List the locations you can reach">
    Each restaurant your app integrates is a **location** a merchant has granted you access to. List the ones you can see:

    ```bash theme={null}
    curl $MAPLE_BASE/locations \
      -H "Authorization: Bearer $MAPLE_KEY"
    ```

    ```json Response theme={null}
    {
      "object": "list",
      "data": [
        { "object": "location", "id": "str_test_123", "name": "Maple Test Kitchen", "status": "active", "timezone": "America/New_York", "...": "..." }
      ]
    }
    ```

    During onboarding we grant your test app at least one test location to build against. Note its `id`.
  </Step>

  <Step title="Connect to a location">
    A grant lets you *see* a location. A **connection** makes your app its order receiver — orders only route to you after this call.

    ```bash theme={null}
    curl -X POST $MAPLE_BASE/locations/str_test_123/connection \
      -H "Authorization: Bearer $MAPLE_KEY"
    ```

    ```json Response theme={null}
    { "object": "connection", "location_id": "str_test_123", "status": "active", "...": "..." }
    ```

    Connections are exclusive per environment: if another app already holds the location, you get a `409`. Read [How Maple works](/developer-api/how-maple-works) for the full grant-versus-connection model.
  </Step>

  <Step title="Receive your first signed webhook">
    Register an HTTPS endpoint you control. (For local testing, a tunnel such as ngrok or Cloudflare Tunnel gives you a public URL.)

    ```bash theme={null}
    curl -X POST $MAPLE_BASE/webhook_subscriptions \
      -H "Authorization: Bearer $MAPLE_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "notification_url": "https://your-app.example.com/maple/webhooks",
        "event_types": ["order.notification"]
      }'
    ```

    The response includes a **one-time signing secret** (`mwhsec_…`). Store it now — it is never shown again.

    ```json Response theme={null}
    {
      "object": "webhook_subscription.created",
      "subscription": { "object": "webhook_subscription", "id": "dws_...", "status": "enabled", "...": "..." },
      "signing_secret": "mwhsec_..."
    }
    ```

    Now fire a synthetic delivery to that endpoint to confirm it's wired up:

    ```bash theme={null}
    curl -X POST $MAPLE_BASE/webhook_subscriptions/dws_.../test \
      -H "Authorization: Bearer $MAPLE_KEY"
    ```

    ```json Response theme={null}
    { "object": "webhook_test_result", "event_id": "evt_...", "delivered": true, "response_status": 200 }
    ```

    <Check>
      `delivered: true` with a `2xx` `response_status` means Maple reached your endpoint and it accepted the event. You're receiving webhooks.
    </Check>
  </Step>
</Steps>

## You just did the whole loop in miniature

Authenticate, find a location, connect to it, and receive a signed event — that's the spine of every Maple integration. Everything else is filling it in.

## Where to go next

<CardGroup cols={2}>
  <Card title="Receive and decide orders" icon="receipt" href="/developer-api/guides/receive-orders">
    Verify webhook signatures and drive real orders with accept / deny / ready / complete.
  </Card>

  <Card title="Publish a menu" icon="book-open" href="/developer-api/guides/publish-menu">
    Push a location's menu so the items in your orders map to your own IDs.
  </Card>

  <Card title="Webhooks in depth" icon="bell" href="/developer-api/concepts/webhooks">
    Signature verification, delivery guarantees, retries, and replay.
  </Card>

  <Card title="Authentication" icon="key" href="/developer-api/concepts/authentication">
    API keys, environments, and scopes.
  </Card>
</CardGroup>