> ## 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 仪表盘](https://app.agentwallex.com)。
2. 导航至 **Settings > API Keys**。
3. 点击 **Create API Key**。
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` 文件中。