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

# 身份验证

> 集成如何连接 MoonUP，以及密钥能访问哪些内容。

密钥在卖家后台的 **卖家 → API 密钥** 中创建。它只显示一次，并在被撤销之前代表该账户执行操作。

## 发送密钥

每个请求都携带密钥，没有需要兑换的中间令牌。

```http theme={null}
GET /v1/offers/my HTTP/1.1
Host: api.moonup.gg
Authorization: Bearer moonup_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```bash theme={null}
curl -H "Authorization: Bearer $MOONUP_API_KEY" https://api.moonup.gg/v1/offers/my
```

仅支持 HTTPS。通过明文 HTTP 传输过的密钥应视为已泄露并立即轮换。

## 密钥能访问什么

卖家自己的商品：列出（`GET /v1/offers/my`）、创建、编辑、管理库存单元、下架和归档。后台中需要第二重验证保护的操作——更改账户邮箱、双重验证设置、提现——密钥均无法访问。

## 地址白名单

可选。如果你的集成从固定地址运行，可在创建密钥时列出这些地址（单个地址或子网，最多 16 条），来自其他地址的请求将被拒绝。列表为空表示允许任意地址。

## 速率限制

| 配额       | 限制               |
| -------- | ---------------- |
| 读取       | 每分钟 500 次请求      |
| 写入       | 每分钟 250 次请求      |
| 对单个商品的写入 | 每分钟 5 次，每小时 10 次 |

超出限制会返回 `429`。这是临时拒绝：稍等后重试即可，密钥依然有效。

## 轮换密钥

每个账户最多可持有 5 个密钥。请在需要之前创建替换密钥：将集成切换到新密钥，确认其正常工作，然后撤销旧密钥。期间无需停机。

## 错误

| 代码                 | 含义                                                 |
| ------------------ | -------------------------------------------------- |
| `401 unauthorized` | 密钥未知、已撤销，或请求来自白名单之外的地址。不会透露具体是哪项检查失败               |
| `403 forbidden`    | 密钥有效，但账户无权执行此操作——缺少权限，或账户已被暂停（`account_suspended`） |
| `429 rate_limited` | 超出了上述某项配额                                          |