跳转到主要内容

​
概述

API 密钥用于认证您的服务器端应用与 AgentWallex API 之间的通信。每个密钥以 awx_ 前缀开头，并绑定到您的账户。

​
创建 API 密钥

通过仪表盘或 REST API（需要 JWT 认证）创建 API 密钥：

​
通过仪表盘

  1. 登录 AgentWallex 仪表盘。
  2. 导航至 Settings > API Keys。
  3. 点击 Create API Key。
  4. 为密钥指定一个描述性名称（例如 production-backend、staging-ci）。
  5. 复制并安全存储密钥 — 该密钥仅显示一次。

​
通过 API

curl -X POST https://api.agentwallex.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"name": "production-backend"}'
完整的 API 密钥仅在创建时返回一次。请立即将其存储到安全的密钥管理器中。

​
列出 API 密钥

curl -X GET https://api.agentwallex.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOi..."
响应包含密钥元数据，但不会返回完整密钥值： 
{
  "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 密钥

1

创建新密钥

通过仪表盘或 API 创建新的 API 密钥。
2

更新应用程序

将新密钥部署到应用程序的环境变量中。
3

验证新密钥可用

确认使用新密钥的 API 调用能正常工作。
4

删除旧密钥

删除旧密钥以防止未授权访问：
curl -X DELETE https://api.agentwallex.com/api/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer eyJhbGciOi..."
至少每 90 天轮换一次 API 密钥。设置日历提醒或通过 CI/CD 流水线自动化轮换。

​
速率限制

API 速率限制取决于您的计划等级：
计划请求/分钟请求/天并发连接数
Starter6010,0005
Growth300100,00025
Enterprise自定义自定义自定义
当您超过速率限制时，API 将返回 429 Too Many Requests 响应，并附带 Retry-After 头： 
{
  "code": "rate_limit_exceeded",
  "type": "rate_limit_error",
  "message": "Rate limit exceeded. Retry after 30 seconds."
}
速率限制按 API 密钥应用。如果需要更高的限制，请联系 AgentWallex 团队或升级您的计划。

​
最佳实践

  • 每个环境一个密钥 — 为开发、预发布和生产环境使用不同的密钥。
  • 使用描述性名称 — 包含环境和服务名称（例如 prod-payment-service）。
  • 监控使用情况 — 检查 last_used_at 以识别应该删除的未使用密钥。
  • 切勿共享密钥 — 每个团队成员或服务应拥有自己的密钥。
  • 使用密钥管理器 — 将密钥存储在 AWS Secrets Manager、HashiCorp Vault 或类似工具中，而非磁盘上的 .env 文件中。