> ## 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-hant/brand/moove-handle)，並為預設錢包設好了[結算代幣](/zh-hant/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-hant/transact/moove-agentic-payments">
    讓 AI 工具替你完成整合。
  </Card>

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

範圍明確、可以撤銷、屬於你。你的資金。你的行動。