跳转到主要内容

​
认证方式

AgentWallex 支持两种认证方式：
方式请求头使用场景
API 密钥X-API-Key: awx_...SDK 和服务器到服务器集成
JWT Bearer 令牌Authorization: Bearer eyJ...Web 应用、OAuth 和仪表盘会话

​
API 密钥认证

API 密钥是服务器端和 SDK 集成的推荐方式。每个密钥以 awx_ 前缀开头。 
curl -X GET https://api.agentwallex.com/api/v1/agents \
  -H "X-API-Key: awx_your_api_key"
切勿在客户端代码、公开仓库或日志中暴露您的 API 密钥。请始终从环境变量中加载。

​
环境变量

将您的 API 密钥存储为环境变量： 
AGENTWALLEX_API_KEY=awx_your_api_key

​
JWT Bearer 令牌认证

对于 Web 应用和 OAuth 流程，请使用 JWT Bearer 令牌。令牌通过 Google OAuth 流程获取：
1

发起 OAuth 流程

将用户重定向到 Google OAuth 端点：
GET /auth/google/redirect
2

处理回调

认证完成后，Google 会将用户重定向到您的回调 URL，并附带一次性代码：
GET /auth/google/callback
3

交换令牌

用一次性代码交换访问令牌和刷新令牌：
curl -X POST https://api.agentwallex.com/api/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{"exchange_code": "one_time_code"}'
4

使用访问令牌

在 Authorization 请求头中包含访问令牌：
curl -X GET https://api.agentwallex.com/api/v1/agents \
  -H "Authorization: Bearer eyJhbGciOi..."

​
刷新令牌

访问令牌会过期。使用刷新令牌获取新的访问令牌： 
curl -X POST https://api.agentwallex.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your_refresh_token"}'

​
登出

使当前会话失效： 
curl -X POST https://api.agentwallex.com/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOi..."

​
安全最佳实践

遵循以下实践以确保集成的安全性。
  • 使用环境变量 — 切勿在源代码中硬编码 API 密钥。
  • 定期轮换密钥 — 至少每 90 天轮换一次 API 密钥。请参阅 API 密钥了解轮换说明。
  • 使用最小权限范围 — 为每个环境（沙盒与生产）创建单独的 API 密钥。
  • 启用 IP 白名单 — Growth 和 Enterprise 计划支持将 API 访问限制为已知 IP。
  • 监控审计日志 — 在仪表盘中或通过 GET /audit-logs 查看认证事件。
  • 开发时使用沙盒 — 切勿使用生产密钥或真实资金进行测试。