> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/vi/cac-be-mat-quan-tri-dung-chung/api-keys.md).

# API Keys

## Tổng quan

Khóa API cung cấp xác thực cho truy cập theo chương trình vào VergeOS REST API và các dịch vụ tích hợp. Mỗi khóa API được gắn với một tài khoản người dùng cụ thể và kế thừa quyền cũng như mức truy cập của người dùng đó. Điều này cho phép các ứng dụng, script và công cụ bên thứ ba tương tác với VergeOS mà không cần các phiên đăng nhập tương tác.

**Các mục đích sử dụng phổ biến của khóa API:**

* Xác thực REST API cho tự động hóa và tích hợp
* Truy cập bộ định tuyến AI tương thích với OpenAI
* Tích hợp công cụ bên thứ ba (giám sát, điều phối, công cụ IaC)
* Xác thực pipeline CI/CD

## Hiểu về Xác thực Khóa API

Khóa API trong VergeOS hoạt động như các token Bearer trong header HTTP Authorization. Không giống như token phiên được tạo trong khi đăng nhập giao diện người dùng (vốn hết hạn sau thời gian không hoạt động), khóa API vẫn hợp lệ cho đến ngày hết hạn được cấu hình hoặc khi bị xóa thủ công.

Mỗi khóa API kế thừa tất cả quyền từ tài khoản người dùng được liên kết. Một khóa API được tạo cho người dùng Tenant Admin sẽ có đặc quyền Tenant Admin, trong khi khóa dành cho System Admin sẽ có quyền truy cập toàn hệ thống.

{% hint style="info" %}
**Khóa API so với Token Phiên**

Token phiên là thông tin xác thực tạm thời và hết hạn sau thời gian không hoạt động. Khóa API được thiết kế cho truy cập theo chương trình dài hạn và vẫn hợp lệ cho đến khi hết hạn hoặc bị xóa.
{% endhint %}

## Tạo khóa API

### Đi tới Quản lý Khóa API

1. Từ menu chính của VergeOS, đi tới **Hệ thống > Người dùng**
2. Chọn tài khoản người dùng sẽ sở hữu khóa API
3. Trong bảng điều khiển người dùng, nhấp vào **API Keys** tiện ích để xem các khóa hiện có

Phần Khóa API hiển thị một bảng với:

* **Tên**: Định danh mô tả cho mỗi khóa
* **Lần đăng nhập gần nhất**: Dấu thời gian xác thực gần nhất
* **IP lần đăng nhập gần nhất**: IP nguồn của lần xác thực gần nhất
* **Hết hạn**: Số ngày còn lại đến khi hết hạn
* **Đã tạo**: Dấu thời gian tạo khóa

### Tạo Khóa API Mới

1. Nhấp **+ Khóa API Mới** ở cuối bảng Khóa API
2. Biểu mẫu mở ra với hai bảng: **Khóa API** (bên trái) và **Truy cập** (bên phải)

### Cấu hình Cài đặt Khóa API

**Tên** (Bắt buộc) Nhập một định danh mô tả cho khóa API. Đặt tên rõ ràng giúp theo dõi và quản lý khóa tốt hơn.

**Mô tả** (Tùy chọn) Thêm ngữ cảnh bổ sung về mục đích của khóa, người yêu cầu hoặc các hệ thống liên quan.

**Loại hết hạn** Chọn cách quản lý thời hạn hiệu lực của khóa:

* **Đặt ngày**: Xác định ngày hết hạn cụ thể (khuyến nghị vì bảo mật)
* **Không bao giờ hết hạn**: Tạo khóa vĩnh viễn (sử dụng thận trọng)

**Hết hạn** (Khi chọn "Đặt ngày") Sử dụng bộ chọn ngày/giờ để đặt thời điểm khóa sẽ hết hạn. Các khoảng hết hạn phổ biến là 30, 60 hoặc 90 ngày.

### Cấu hình Kiểm soát Truy cập

**Danh sách Cho phép IP** Hạn chế khóa API đối với các địa chỉ IP hoặc phạm vi CIDR cụ thể. Chỉ các địa chỉ được liệt kê mới có thể xác thực bằng khóa này.

1. Nhấp **+ (dấu cộng)** biểu tượng để thêm một mục
2. Nhập một địa chỉ IP (ví dụ, `192.168.1.100`) hoặc phạm vi CIDR (ví dụ, `192.168.1.0/24`)
3. Đánh dấu ô chọn để bật mục
4. Thêm các mục bổ sung khi cần

**Danh sách Chặn IP** Chặn các địa chỉ IP hoặc phạm vi cụ thể sử dụng khóa này, đồng thời cho phép tất cả các địa chỉ khác.

1. Nhấp **+ (dấu cộng)** biểu tượng để thêm một mục
2. Nhập địa chỉ IP hoặc phạm vi CIDR để chặn
3. Đánh dấu ô chọn để bật mục

{% hint style="info" %}
**Ưu tiên giữa Danh sách Cho phép và Chặn**

Khi cả hai danh sách đều được cấu hình, Danh sách Cho phép IP sẽ được ưu tiên. Nếu một địa chỉ xuất hiện trong cả hai danh sách, Danh sách Cho phép sẽ quyết định quyền truy cập.
{% endhint %}

### Lưu và Lấy Khóa API

1. Rà soát tất cả cài đặt để đảm bảo chính xác
2. Nhấp **Gửi** để tạo khóa API

Một cửa sổ bật lên hiển thị khóa API được tạo với hai tùy chọn:

* **Sao chép**: Nhấp để sao chép toàn bộ chuỗi khóa vào clipboard của bạn
* **Lưu**: Nhấp để tải xuống khóa dưới dạng tệp `.PAK` (tệp Khóa API được bảo vệ)

{% hint style="danger" %}
**Hiển thị một lần**

Khóa API đầy đủ chỉ được hiển thị tại thời điểm tạo. Khi bạn đóng cửa sổ bật lên này, không thể truy xuất lại khóa đầy đủ. Nếu bạn làm mất khóa, bạn phải xóa nó và tạo một khóa mới.
{% endhint %}

Sau khi bảo vệ khóa, đóng cửa sổ bật lên. Khóa API mới sẽ xuất hiện trong bảng Khóa API.

## Quản lý Các Khóa API Hiện Có

### Chỉnh sửa Khóa API

1. Trong bảng Khóa API, tìm khóa bạn muốn sửa đổi
2. Nhấp **Chỉnh sửa** (biểu tượng bút chì) bên cạnh tên khóa
3. Cập nhật các cài đặt (tên, mô tả, thời hạn hết hạn, danh sách IP)
4. Nhấp **Gửi** để lưu thay đổi

{% hint style="info" %}
**Không Thể Thay Đổi Chuỗi Khóa**

Chỉnh sửa khóa API chỉ cập nhật siêu dữ liệu và kiểm soát truy cập của nó. Chuỗi khóa thực tế không thể được sửa đổi. Để thay đổi chuỗi khóa, bạn phải tạo một khóa API mới và xóa khóa cũ.
{% endhint %}

### Xóa Khóa API

1. Trong bảng Khóa API, tìm khóa bạn muốn xóa
2. Nhấp **Xóa** (biểu tượng thùng rác) bên cạnh tên khóa
3. Xác nhận việc xóa

{% hint style="warning" %}
**Thu hồi ngay lập tức**

Xóa một khóa API sẽ ngay lập tức thu hồi toàn bộ quyền truy cập. Bất kỳ ứng dụng hoặc script nào sử dụng khóa đã xóa sẽ không thể xác thực.
{% endhint %}

## Sử dụng Khóa API

### Định dạng Xác thực

Khóa API được dùng trong header HTTP Authorization dưới dạng token Bearer:

```
Authorization: Bearer <chuỗi-khóa-api-của-bạn>
```

### Yêu cầu API Ví dụ

```bash
curl -X GET "https://your-vergeos-instance/api/v4/system" \
  -H "Authorization: Bearer chuỗi-khóa-api-của-bạn" \
  -H "Content-Type: application/json"
```

### Lưu Trữ Biến Môi Trường

Vì lý do bảo mật, hãy tải khóa API từ các biến môi trường thay vì mã hóa cứng chúng:

```bash
# Đặt biến môi trường
export VERGEOS_API_KEY="chuỗi-khóa-api-của-bạn"

# Sử dụng trong yêu cầu API
curl -X GET "https://your-vergeos-instance/api/v4/system" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"
```

## Các Lưu Ý Bảo Mật

**Xử lý Khóa API Như Mật Khẩu** Khóa API cung cấp xác thực đầy đủ với tư cách người dùng được liên kết. Hãy bảo vệ chúng cẩn thận như mật khẩu.

**Sử dụng Hạn Chế IP** Cấu hình Danh sách Cho phép IP bất cứ khi nào có thể để giới hạn nơi khóa có thể được sử dụng. Điều này giúp giảm đáng kể rủi ro nếu khóa bị xâm phạm.

**Đặt Ngày Hết Hạn** Tránh dùng khóa vĩnh viễn khi có thể. Việc hết hạn định kỳ buộc phải xoay vòng khóa và giới hạn khoảng thời gian phơi nhiễm.

**Theo Dõi Việc Sử Dụng Khóa** Thường xuyên xem lại các trường "Lần đăng nhập gần nhất" và "IP lần đăng nhập gần nhất" để xác định các mẫu truy cập bất thường.

**Xóa Các Khóa Không Dùng** Loại bỏ các khóa API không còn cần thiết để giảm thiểu bề mặt tấn công của bạn.

## Khắc phục sự cố

**Xác thực Khóa API Thất Bại**

Xác minh rằng khóa được đưa vào đúng cách trong header Authorization dưới dạng token Bearer. Kiểm tra xem có khoảng trắng thừa hoặc bị cắt ngắn không.

**Từ Chối Truy Cập dù Có Khóa Hợp Lệ**

Kiểm tra danh sách Cho phép/Chặn IP. IP nguồn của bạn có thể không được phép hoặc có thể nằm trong danh sách Chặn.

**Khóa Đã Hết Hạn**

Kiểm tra cột "Hết hạn" trong bảng Khóa API. Tạo một khóa mới nếu khóa cũ đã hết hạn.

**Không Thể Khôi Phục Khóa Bị Mất**

Không thể khôi phục khóa API sau khi đóng cửa sổ bật lên tạo ban đầu. Hãy xóa khóa bị mất và tạo một khóa mới.

## Tài Nguyên Liên Quan

* [Tài liệu VergeOS REST API](/knowledge-base/vi/automation-api/verge-api-guide.md) - Tài liệu tham khảo API đầy đủ và các endpoint


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/automate-protect-and-extend/vi/cac-be-mat-quan-tri-dung-chung/api-keys.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.