> ## 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.

# Xác thực

> Cách xác thực với API AgentWallex sử dụng khóa API hoặc token JWT.

## Phương thức Xác thực

AgentWallex hỗ trợ hai phương thức xác thực:

| Phương thức      | Header                         | Trường hợp sử dụng                     |
| ---------------- | ------------------------------ | -------------------------------------- |
| API Key          | `X-API-Key: awx_...`           | SDK và tích hợp server-to-server       |
| JWT Bearer Token | `Authorization: Bearer eyJ...` | Ứng dụng web, OAuth và phiên dashboard |

## Xác thực bằng API Key

Khóa API là phương pháp được khuyến nghị cho tích hợp phía server và SDK. Mọi khóa bắt đầu bằng tiền tố `awx_`.

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

<Warning>
  Không bao giờ để lộ khóa API trong mã phía client, kho lưu trữ công khai hoặc nhật ký. Luôn tải nó từ biến môi trường.
</Warning>

### Biến môi trường

Lưu trữ khóa API dưới dạng biến môi trường:

<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>

## Xác thực bằng JWT Bearer Token

Đối với ứng dụng web và luồng OAuth, sử dụng JWT bearer token. Token được lấy thông qua luồng Google OAuth:

<Steps>
  <Step title="Bắt đầu luồng OAuth">
    Chuyển hướng người dùng đến endpoint Google OAuth:

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

  <Step title="Xử lý callback">
    Sau khi xác thực, Google chuyển hướng đến URL callback của bạn với mã một lần:

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

  <Step title="Đổi lấy token">
    Đổi mã một lần lấy access và refresh token:

    ```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="Sử dụng access token">
    Đưa access token vào header `Authorization`:

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

### Làm mới Token

Access token có thời hạn. Sử dụng refresh token để lấy access token mới:

```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"}'
```

### Đăng xuất

Vô hiệu hóa phiên hiện tại:

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

## Các phương pháp Bảo mật tốt nhất

<Tip>
  Tuân thủ các phương pháp này để giữ cho tích hợp của bạn an toàn.
</Tip>

* **Sử dụng biến môi trường** — Không bao giờ mã hóa cứng khóa API trong mã nguồn.
* **Xoay khóa thường xuyên** — Xoay khóa API ít nhất mỗi 90 ngày. Xem [Khóa API](/vi/introduction/api-keys) để biết hướng dẫn xoay khóa.
* **Sử dụng phạm vi tối thiểu cần thiết** — Tạo khóa API riêng biệt cho mỗi môi trường (sandbox và production).
* **Bật danh sách IP cho phép** — Có sẵn trên gói Growth và Enterprise để hạn chế truy cập API từ các IP đã biết.
* **Giám sát nhật ký kiểm toán** — Xem xét các sự kiện xác thực trong dashboard hoặc qua `GET /audit-logs`.
* **Sử dụng sandbox cho phát triển** — Không bao giờ thử nghiệm với khóa production hoặc quỹ thực.