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

# 身份验证

> 每个请求都携带 Bearer API 密钥。密钥决定所属环境，并携带您的应用所拥有的权限范围（scope）。

向 Developer API 发送的每个请求，都要在 `Authorization` 请求头中携带 `Bearer` API 密钥：

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

一个密钥同时回答三个问题：您是**哪个应用**、属于**哪个环境**（沙盒或生产），以及拥有**哪些权限范围**。您可以用 `GET /v1/me` 验证任何密钥，它会返回的正是这些信息。

每个环境都有各自的基础 URL：沙盒为 `https://api.staging.maple.inc/v1`，生产为 `https://api.maple.inc/v1`。请使用与主机相匹配的密钥。请参阅[环境](/zh/developer-api/concepts/environments)。

## API 密钥

Maple 会批准您的应用及其权限范围上限。受邀的组织成员可在 **Developers → your app → Overview & keys** 中创建和吊销密钥。请登录与密钥所属环境对应的控制台（沙盒密钥使用 `https://app.staging.maple.inc`，生产密钥使用 `https://app.maple.inc`）；无需选择商户或餐厅。

| 密钥 | 环境 | 基础 URL |
| - | - | - |
| `mpk_test_…` | 沙盒 | `https://api.staging.maple.inc/v1` |
| `mpk_live_…` | 生产 | `https://api.maple.inc/v1` |

每个请求都要把密钥作为 bearer 令牌发送，并使用其所属环境的基础 URL。请把密钥保存在服务器端；切勿将其嵌入客户端应用，也不要提交到源代码管理中。缩小应用的权限范围会立即对其现有密钥生效。

<Warning>
  **完整密钥只显示一次。** 在关闭创建对话框之前，请先把它保存到您的密钥管理工具中。密钥列表只显示元数据和最后四位字符，无法恢复密钥本身。请不要让密钥出现在日志、截图和支持消息中。
</Warning>

要更换密钥，请创建新密钥、更新您的客户端、确认其可用，然后明确吊销旧密钥。吊销后，该密钥会立即无法通过身份验证。被暂停或吊销的应用无法使用其任何密钥进行身份验证，但仍可通过控制台进行检查和保护性吊销。

密钥**不会**授予门店访问权限、创建沙盒，或批准生产环境使用。应用所有权、权限范围上限、门店授权和生产批准均由 Maple 单独管理。仅有员工权限，并不能访问开发者控制台中未关联的应用。

请按照[快速入门](/zh/developer-api/quickstart)创建密钥，并通过 `/v1/me` 验证返回的应用和环境。

## 权限范围（Scopes）

访问受权限范围控制，因此您的应用只拥有其所需的权限：

| 权限范围 | 授予的权限 |
| - | - |
| `locations:read` | 列出并读取已授权的门店 |
| `connections:read` / `connections:write` | 读取或管理门店连接 |
| `orders:read` / `orders:write` | 读取订单或提交订单决策 |
| `menus:read` / `menus:write` | 读取或发布门店的菜单 |
| `delivery_zones:read` / `delivery_zones:write` | 读取或管理已连接门店的外送范围，并检查是否可送达 |
| `webhooks:read` / `webhooks:write` | 读取或管理 webhook 订阅 |
| `bookings:read` | 读取已授权门店的预订、资料、可订时段、配置和实时桌位情况 |
| `bookings:write` | 为客人保留时段，并创建、更改或取消预订 |
| `bookings:manage` | 代表场所操作：确认、拒绝、安排入座、完成、取消预订或标记预订为未到店，并为散客安排入座 |
| `bookings:configure` | 发布原生预订配置 |

缺少所需权限范围的请求会返回 `403`，代码为 `insufficient_scope`。在错误的环境中使用密钥会返回 `403`，代码为 `wrong_environment`。请参阅[错误](/zh/developer-api/concepts/errors)。

<Tip>
  无需发起真实调用，也能查看密钥可以做什么：`GET /v1/me` 会返回应用、其所属环境及其生效的权限范围。
</Tip>

## OAuth

<Note>
  **建设中。** 基于 OAuth 的访问（商户委托令牌和 `client_credentials` 授权）尚未纳入正式发布的 Developer API。目前请使用 API 密钥。如果您的集成需要 OAuth，请联系 Maple 团队；流程确定后，本节会进行扩充。
</Note>


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