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

# API 金鑰

> 建立、管理和輪換 AgentWallex 整合的 API 金鑰。

## 概覽

API 金鑰用於驗證您的伺服器端應用程式與 AgentWallex API 之間的身份。每個金鑰以 `awx_` 前綴開頭，並與您的帳戶綁定。

## 建立 API 金鑰

透過儀表板或 REST API（需要 JWT 身份驗證）建立 API 金鑰：

### 透過儀表板

1. 登入 [AgentWallex Dashboard](https://app.agentwallex.com)。
2. 前往**設定 > API 金鑰**。
3. 點擊**建立 API 金鑰**。
4. 為金鑰取一個描述性名稱（例如 `production-backend`、`staging-ci`）。
5. 複製並安全儲存金鑰 — 它只會顯示一次。

### 透過 API

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"name": "production-backend"}'
```

<Warning>
  完整的 API 金鑰僅在建立時回傳一次。請立即將其儲存在安全的密鑰管理工具中。
</Warning>

## 列出 API 金鑰

```bash theme={null}
curl -X GET https://api.agentwallex.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOi..."
```

回應包含金鑰的中繼資料，但不會包含完整的金鑰值：

```json theme={null}
{
  "data": [
    {
      "id": "key_abc123",
      "name": "production-backend",
      "prefix": "awx_...x4f2",
      "created_at": "2025-06-01T10:00:00Z",
      "last_used_at": "2025-06-15T14:30:00Z"
    }
  ]
}
```

## 輪換 API 金鑰

<Steps>
  <Step title="建立新金鑰">
    透過儀表板或 API 建立新的 API 金鑰。
  </Step>

  <Step title="更新您的應用程式">
    將新金鑰部署到應用程式的環境變數中。
  </Step>

  <Step title="驗證新金鑰是否正常運作">
    確認使用新金鑰的 API 呼叫成功。
  </Step>

  <Step title="刪除舊金鑰">
    移除舊金鑰以防止未經授權的存取：

    ```bash theme={null}
    curl -X DELETE https://api.agentwallex.com/api/v1/api-keys/key_abc123 \
      -H "Authorization: Bearer eyJhbGciOi..."
    ```
  </Step>
</Steps>

<Tip>
  至少每 90 天輪換一次 API 金鑰。設定日曆提醒或透過 CI/CD 管線自動化輪換。
</Tip>

## 速率限制

API 速率限制取決於您的方案等級：

| 方案         | 請求/分鐘 | 請求/天    | 並行連線 |
| ---------- | ----- | ------- | ---- |
| Starter    | 60    | 10,000  | 5    |
| Growth     | 300   | 100,000 | 25   |
| Enterprise | 自訂    | 自訂      | 自訂   |

當您超過速率限制時，API 會回傳 `429 Too Many Requests` 回應，並帶有 `Retry-After` 標頭：

```json theme={null}
{
  "code": "rate_limit_exceeded",
  "type": "rate_limit_error",
  "message": "Rate limit exceeded. Retry after 30 seconds."
}
```

<Note>
  速率限制按 API 金鑰計算。如果您需要更高的限制，請聯繫 AgentWallex 團隊或升級您的方案。
</Note>

## 最佳實踐

* **每個環境一個金鑰** — 為開發、預備和正式環境使用獨立的金鑰。
* **為金鑰取描述性名稱** — 包含環境和服務名稱（例如 `prod-payment-service`）。
* **監控使用情況** — 檢查 `last_used_at` 以識別應刪除的未使用金鑰。
* **切勿共用金鑰** — 每個團隊成員或服務應有各自的金鑰。
* **使用密鑰管理工具** — 將金鑰儲存在 AWS Secrets Manager、HashiCorp Vault 或類似工具中，而非磁碟上的 `.env` 檔案。