> 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/run-the-platform/vi/quan-tri-he-thong/api-keys.md).

# Khóa API

## Tổng quan

Các khóa API cung cấp xác thực cho truy cập theo chương trình tới 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 hạn cũng như cấp độ 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 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

Trong VergeOS, khóa API hoạt động như các Bearer token trong tiêu đề HTTP Authorization. Không giống như token phiên được tạo trong quá trình đăng nhập giao diện người dùng (vốn hết hạn sau khi 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 hạ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 cho System Admin sẽ có quyền truy cập trên 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 khi 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 VergeOS, điều hướng đến **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 **Khóa API** 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**: Mã định danh mô tả cho từng khóa
* **Lần đăng nhập gần nhất**: Dấu thời gian xác thực gần đây nhất
* **IP đăng nhập gần nhất**: Địa chỉ 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 cho đế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 vào **+ 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ã đị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.

**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ì lý do bảo mật)
* **Không bao giờ hết hạn**: Tạo khóa vĩnh viễn (hãy 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 thời hạn 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 IP cho phép** Hạn chế khóa API chỉ cho các địa chỉ IP hoặc dải 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 vào **+ (dấu cộng)** biểu tượng để thêm một mục
2. Nhập địa chỉ IP (ví dụ, `192.168.1.100`) hoặc dải CIDR (ví dụ, `192.168.1.0/24`)
3. Chọn hộp kiểm để bật mục này
4. Thêm các mục bổ sung khi cần

**Danh sách IP từ chối** Chặn các địa chỉ IP hoặc dải cụ thể khỏi việc sử dụng khóa này trong khi vẫn cho phép tất cả các địa chỉ khác.

1. Nhấp vào **+ (dấu cộng)** biểu tượng để thêm một mục
2. Nhập địa chỉ IP hoặc dải CIDR cần chặn
3. Chọn hộp kiểm để bật mục này

{% hint style="info" %}
**Ưu tiên giữa danh sách cho phép và danh sách từ chối**

Khi cả hai danh sách đều được cấu hình, Danh sách IP cho phép 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à truy xuất khóa API

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

Một cửa sổ bật lên hiển thị khóa API đã 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 bộ nhớ tạm
* **Lưu**: Nhấp để tải khóa xuống dưới dạng một `.PAK` tệp (Khóa API được bảo vệ)

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

Khóa API đầy đủ chỉ được hiển thị tại thời điểm tạo. Sau 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 mất khóa, bạn phải xóa nó và tạo khóa mới.
{% endhint %}

Sau khi lưu trữ an toàn khóa, hãy đó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, xác định vị trí khóa bạn muốn sửa đổi
2. Nhấp vào **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ài đặt (tên, mô tả, hết hạn, danh sách IP)
4. Nhấp vào **Gửi** để lưu các thay đổi

{% hint style="info" %}
**Chuỗi khóa không thể thay đổi**

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ể 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, xác định vị trí khóa bạn muốn xóa
2. Nhấp vào **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 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 đang 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 tiêu đề HTTP Authorization dưới dạng Bearer token:

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

### Yêu cầu API mẫu

```bash
curl -X GET "https://your-vergeos-instance/api/v4/system" \\
  -H "Authorization: Bearer your-api-key-string-here" \\
  -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ừ biến môi trường thay vì viết 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 cân nhắc về bảo mật

**Hãy xem 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 IP cho phép 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 làm giảm đáng kể rủi ro nếu một khóa bị lộ.

**Đặ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 đăng nhập gần nhất" để phát hiện các mẫu truy cập bất thường.

**Xóa các khóa không dùng** Xóa 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 tiêu đề Authorization dưới dạng Bearer token. Kiểm tra xem có khoảng trắng thừa hoặc bị cắt ngắn không.

**Bị từ chối truy cập từ khóa hợp lệ**

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

**Khóa đã hết hạn**

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

**Không thể truy xuất khóa bị mất**

Không thể khôi phục khóa API sau khi cửa sổ bật lên tạo ban đầu đã bị đóng. Hãy xóa khóa bị mất và tạo 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 và các endpoint đầy đủ


---

# 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/run-the-platform/vi/quan-tri-he-thong/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.