> ## 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 密钥或 JWT 令牌进行 AgentWallex API 身份认证。

## 认证方式

AgentWallex 支持两种认证方式：

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

## API 密钥认证

API 密钥是服务器端和 SDK 集成的推荐方式。每个密钥以 `awx_` 前缀开头。

```bash theme={null}
curl -X GET https://api.agentwallex.com/api/v1/agents \
  -H "X-API-Key: awx_your_api_key"
```

<Warning>
  切勿在客户端代码、公开仓库或日志中暴露您的 API 密钥。请始终从环境变量中加载。
</Warning>

### 环境变量

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

<CodeGroup>
  ```bash .env theme={null}
  AGENTWALLEX_API_KEY=awx_your_api_key
  ```

  ```typescript TypeScript theme={null}
  import { AgentWallex } from "@agentwallex/sdk";

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

  ```python Python theme={null}
  import os
  from agentwallex import AgentWallex

  aw = AgentWallex(api_key=os.environ["AGENTWALLEX_API_KEY"])
  ```
</CodeGroup>

## JWT Bearer 令牌认证

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

<Steps>
  <Step title="发起 OAuth 流程">
    将用户重定向到 Google OAuth 端点：

    ```
    GET /auth/google/redirect
    ```
  </Step>

  <Step title="处理回调">
    认证完成后，Google 会将用户重定向到您的回调 URL，并附带一次性代码：

    ```
    GET /auth/google/callback
    ```
  </Step>

  <Step title="交换令牌">
    用一次性代码交换访问令牌和刷新令牌：

    ```bash theme={null}
    curl -X POST https://api.agentwallex.com/api/v1/auth/exchange \
      -H "Content-Type: application/json" \
      -d '{"exchange_code": "one_time_code"}'
    ```
  </Step>

  <Step title="使用访问令牌">
    在 `Authorization` 请求头中包含访问令牌：

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

### 刷新令牌

访问令牌会过期。使用刷新令牌获取新的访问令牌：

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your_refresh_token"}'
```

### 登出

使当前会话失效：

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

## 安全最佳实践

<Tip>
  遵循以下实践以确保集成的安全性。
</Tip>

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