身份认证

认证方式

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

import { AgentWallex } from "@agentwallex/sdk";

const aw = new AgentWallex({
  apiKey: process.env.AGENTWALLEX_API_KEY!,
});

import os
from agentwallex import AgentWallex

aw = AgentWallex(api_key=os.environ["AGENTWALLEX_API_KEY"])

JWT Bearer 令牌认证

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

发起 OAuth 流程

将用户重定向到 Google OAuth 端点：

GET /auth/google/redirect

处理回调

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

GET /auth/google/callback

交换令牌

用一次性代码交换访问令牌和刷新令牌：

curl -X POST https://api.agentwallex.com/api/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{"exchange_code": "one_time_code"}'

使用访问令牌

在 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 查看认证事件。
开发时使用沙盒 — 切勿使用生产密钥或真实资金进行测试。

快速入门

平台

核心功能

使用指南

认证方式

API 密钥认证

环境变量

JWT Bearer 令牌认证

刷新令牌

登出

安全最佳实践

​认证方式

​API 密钥认证

​环境变量

​JWT Bearer 令牌认证

​刷新令牌

​登出

​安全最佳实践

认证方式

API 密钥认证

环境变量

JWT Bearer 令牌认证

刷新令牌

登出

安全最佳实践