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

# Khóa API

> Tạo, quản lý và xoay khóa API cho các tích hợp AgentWallex.

## Tổng quan

Khóa API xác thực các ứng dụng phía server của bạn với API AgentWallex. Mỗi khóa bắt đầu bằng tiền tố `awx_` và được liên kết với tài khoản của bạn.

## Tạo Khóa API

Tạo khóa API thông qua dashboard hoặc REST API (yêu cầu xác thực JWT):

### Qua Dashboard

1. Đăng nhập vào [AgentWallex Dashboard](https://app.agentwallex.com).
2. Điều hướng đến **Settings > API Keys**.
3. Nhấp **Create API Key**.
4. Đặt tên mô tả cho khóa (ví dụ: `production-backend`, `staging-ci`).
5. Sao chép và lưu trữ khóa an toàn — nó chỉ được hiển thị một lần.

### Qua API

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"name": "production-backend"}'
```

<Warning>
  Khóa API đầy đủ chỉ được trả về một lần tại thời điểm tạo. Lưu trữ nó ngay lập tức trong trình quản lý bí mật an toàn.
</Warning>

## Liệt kê Khóa API

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

Phản hồi bao gồm metadata của khóa nhưng không bao giờ chứa giá trị khóa đầy đủ:

```json theme={null}
{
  "data": [
    {
      "id": "key_abc123",
      "name": "production-backend",
      "prefix": "awx_...x4f2",
      "created_at": "2025-06-01T10:00:00Z",
      "last_used_at": "2025-06-15T14:30:00Z"
    }
  ]
}
```

## Xoay Khóa API

<Steps>
  <Step title="Tạo khóa mới">
    Tạo khóa API mới qua dashboard hoặc API.
  </Step>

  <Step title="Cập nhật ứng dụng">
    Triển khai khóa mới vào biến môi trường của ứng dụng.
  </Step>

  <Step title="Xác minh khóa mới hoạt động">
    Xác nhận rằng các cuộc gọi API thành công với khóa mới.
  </Step>

  <Step title="Xóa khóa cũ">
    Xóa khóa cũ để ngăn truy cập trái phép:

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

<Tip>
  Xoay khóa API ít nhất mỗi 90 ngày. Đặt lời nhắc lịch hoặc tự động hóa việc xoay khóa với pipeline CI/CD của bạn.
</Tip>

## Giới hạn Tốc độ

Giới hạn tốc độ API phụ thuộc vào cấp gói của bạn:

| Gói        | Yêu cầu/phút | Yêu cầu/ngày | Kết nối đồng thời |
| ---------- | ------------ | ------------ | ----------------- |
| Starter    | 60           | 10,000       | 5                 |
| Growth     | 300          | 100,000      | 25                |
| Enterprise | Tùy chỉnh    | Tùy chỉnh    | Tùy chỉnh         |

Khi bạn vượt quá giới hạn tốc độ, API trả về phản hồi `429 Too Many Requests` với header `Retry-After`:

```json theme={null}
{
  "code": "rate_limit_exceeded",
  "type": "rate_limit_error",
  "message": "Rate limit exceeded. Retry after 30 seconds."
}
```

<Note>
  Giới hạn tốc độ được áp dụng theo từng khóa API. Nếu bạn cần giới hạn cao hơn, liên hệ đội ngũ AgentWallex hoặc nâng cấp gói của bạn.
</Note>

## Các phương pháp tốt nhất

* **Một khóa cho mỗi môi trường** — Sử dụng khóa riêng biệt cho development, staging và production.
* **Đặt tên khóa mô tả** — Bao gồm tên môi trường và dịch vụ (ví dụ: `prod-payment-service`).
* **Giám sát việc sử dụng** — Kiểm tra `last_used_at` để xác định các khóa không sử dụng cần được xóa.
* **Không bao giờ chia sẻ khóa** — Mỗi thành viên nhóm hoặc dịch vụ nên có khóa riêng.
* **Sử dụng trình quản lý bí mật** — Lưu trữ khóa trong AWS Secrets Manager, HashiCorp Vault hoặc các công cụ tương tự thay vì trong tệp `.env` trên đĩa.