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

# Moove API Keys

> 为 Moove API 创建一个限定范围的 API 密钥，复制一次，用完就永久吊销。

创建一个密钥，复制一次，用它来调用 Moove API。

<Info>
  **仅限网页**，在 [moove.xyz/dashboard/api-keys](https://www.moove.xyz/dashboard/api-keys)。没有手机端的对应界面。
</Info>

## 我怎么创建 API 密钥？

<Steps>
  <Step title="打开管理 → API 密钥">
    在网页仪表板上。
  </Step>

  <Step title="给它命名">
    取一个你六个月后还认得出的名字——它服务的是哪个服务或哪个环境。
  </Step>

  <Step title="选一个代理">
    真实存在的是 **Moove Receive Agent**。它会展开为那个代理所需的权限范围。
  </Step>

  <Step title="复制密钥">
    <Warning>
      明文密钥在创建时 **只显示一次**。现在就复制它，存进你的密钥管理器。不复制就关掉对话框，这个密钥就用不了了——只能再建一个。
    </Warning>
  </Step>
</Steps>

基础网址是 `https://api.moove.xyz`。

## Moove 代理，而不是原始权限范围

你选的是一个 **代理**，不是一串权限字符串。"Moove Receive Agent"是商家能够理解的单位；`payment_link:create` 不是。

| 代理                      | 状态      | 它授予的权限范围                                  |
| ----------------------- | ------- | ----------------------------------------- |
| **Moove Receive Agent** | **已上线** | `payment_link:create`、`payment_link:read` |
| Moove Send Agent        | 即将推出    | —                                         |
| Moove Swap Agent        | 即将推出    | —                                         |
| Moove Ramp Agent        | 即将推出    | —                                         |

那三个即将推出的代理显示为禁用状态。选中其中之一会铸出一个什么都不能做的密钥，所以选择器不让你选。

## API 密钥能做什么，不能做什么

<Note>
  密钥是 **你的一个缩小版**。它以你的账户身份行事，只能做你能做的事情中的一部分。

  **没有任何接口能移动资金。** 支付链接总是结算到你自己的默认钱包，以那个钱包的代币计价——调用方无法指定目的地。泄露的密钥能创建付给 *你* 的收款请求，却无法付给别的任何人。
</Note>

密钥也无法铸出另一个密钥。密钥管理只接受会话认证，所以被窃取的密钥无法为自己提权。

## 我怎么保证密钥安全？

<Warning>
  * 把它存在密钥管理器或环境变量里。绝不要放进源代码管理。
  * 绝不要把它粘贴进提示词、聊天、工单或截图。
  * 每个服务用一个单独的密钥，这样吊销一个不会连累其余的。
  * 有一点不放心的密钥就吊销掉。新建一个只要几秒钟。
</Warning>

## 我最多能有多少个密钥？

每个账户最多 **10 个活跃密钥**。创建第十一个时请求会被拒绝并返回 `TOO_MANY_API_KEYS`——请先吊销一个你不再使用的。

<Tip>
  这个上限是在提醒你按集成而不是按部署来划分密钥。你实际运行的每个服务配一个密钥，既容易理解，情况有变时也容易吊销。
</Tip>

## 我怎么吊销一个密钥？

<Steps>
  <Step title="打开密钥的菜单">
    在 **管理 → API 密钥** 中，打开该密钥那一行的 **…** 菜单，选择 **撤销**。
  </Step>

  <Step title="确认">
    再点击一次 **撤销** 以确认。密钥会立即停止工作。
  </Step>
</Steps>

<Warning>
  **吊销是永久的。** 没有撤销吊销这回事。明文从未被保存过，所以即便记录被恢复，被吊销的密钥也永远无法再次使用。请改为签发一个新密钥。
</Warning>

## 我怎么使用密钥？

在每个请求的 `X-API-Key` 头里发送它。

```bash theme={null}
curl -sS -X POST "https://api.moove.xyz/v1/payment-link" \
  -H "X-API-Key: $MOOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toAmount": "49.99" }'
```

[认证 →](/api-reference/authentication)

## 第一次调用之前

API 不会为一个无法收款的账户创建链接。请确认你已经领取了 [Moove 账号](/zh-hans/brand/moove-handle)，并为默认钱包设好了[结算代币](/zh-hans/concepts/settlement-and-auto-routing)——否则你会收到 `409`。

## 接下来读什么

<CardGroup cols={3}>
  <Card title="认证" icon="lock" href="/api-reference/authentication">
    这个请求头怎么用。
  </Card>

  <Card title="Moove 代理支付" icon="sparkles" href="/zh-hans/transact/moove-agentic-payments">
    让 AI 工具替你完成集成。
  </Card>

  <Card title="Moove Payment Links API" icon="link" href="/api-reference/moove-receive/moove-payment-links">
    完整的接口。
  </Card>
</CardGroup>

范围明确、可以吊销、属于你。你的资金。你的操作。