> ## 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 Key          | `X-API-Key: awx_...`           | SDK 和伺服器對伺服器整合        |
| JWT Bearer Token | `Authorization: Bearer eyJ...` | 網頁應用程式、OAuth 和儀表板工作階段 |

## API Key 身份驗證

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 Token 身份驗證

對於網頁應用程式和 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-Hant/introduction/api-keys)了解輪換說明。
* **使用最小必要範圍** — 為每個環境（沙箱 vs. 正式環境）建立獨立的 API 金鑰。
* **啟用 IP 白名單** — Growth 和 Enterprise 方案可將 API 存取限制於已知 IP。
* **監控稽核日誌** — 在儀表板或透過 `GET /audit-logs` 檢視驗證事件。
* **使用沙箱進行開發** — 切勿使用正式環境金鑰或真實資金進行測試。