> 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/zh/gong-xiang-guan-li-jie-mian/api-keys.md).

# API 密钥

## 概述

API 密钥为 VergeOS REST API 和集成服务提供程序化访问认证。每个 API 密钥都关联到一个特定用户账户，并继承该用户的权限和访问级别。这使应用程序、脚本和第三方工具无需交互式登录会话即可与 VergeOS 交互。

**API 密钥的常见用途：**

* 用于自动化和集成的 REST API 认证
* OpenAI 兼容的 AI 路由器访问
* 第三方工具集成（监控、编排、IaC 工具）
* CI/CD 流水线认证

## 了解 API 密钥认证

VergeOS 中的 API 密钥在 HTTP Authorization 头中作为 Bearer 令牌使用。与 UI 登录期间生成的会话令牌（在无操作后会过期）不同，API 密钥会一直有效，直到其配置的到期日期或被手动删除。

每个 API 密钥都会继承其关联用户账户的全部权限。为 Tenant Admin 用户创建的 API 密钥将具有 Tenant Admin 权限，而为 System Admin 创建的密钥将拥有系统级访问权限。

{% hint style="info" %}
**API 密钥与会话令牌**

会话令牌是会在无操作后过期的临时凭据。API 密钥专为长期程序化访问而设计，并会一直有效，直到过期或被删除。
{% endhint %}

## 创建 API 密钥

### 转到 API 密钥管理

1. 从 VergeOS 主菜单中，转到 **系统 > 用户**
2. 选择将拥有该 API 密钥的用户账户
3. 在用户仪表板中，单击 **API 密钥** 小组件以查看现有密钥

API 密钥部分显示一个表格，包含：

* **名称**：每个密钥的描述性标识符
* **上次登录**：最近一次认证时间戳
* **上次登录 IP**：上次认证的来源 IP
* **到期时间**：距过期还剩的天数
* **创建时间**：密钥生成时间戳

### 创建新的 API 密钥

1. 点击 **+ 新建 API 密钥** 位于 API 密钥表的底部
2. 表单打开后会显示两个面板： **API 密钥** （左侧）和 **访问** （右侧）

### 配置 API 密钥设置

**名称** （必填）输入 API 密钥的描述性标识符。清晰的命名有助于跟踪和管理密钥。

**描述** （可选）添加有关该密钥用途、请求者或相关系统的更多上下文。

**过期类型** 选择如何管理密钥的有效期：

* **设置日期**：定义一个特定的到期日期（建议用于安全性）
* **永不过期**：创建永久密钥（请谨慎使用）

**到期时间** （当选择“设置日期”时）使用日期/时间选择器设置密钥应在何时过期。常见的过期周期为 30、60 或 90 天。

### 配置访问控制

**IP 允许列表** 将 API 密钥限制为特定 IP 地址或 CIDR 范围。只有列出的地址才能使用此密钥进行认证。

1. 点击 **+（加号）** 用于添加条目的图标
2. 输入一个 IP 地址（例如， `192.168.1.100`）或 CIDR 范围（例如， `192.168.1.0/24`)
3. 勾选复选框以启用该条目
4. 根据需要添加其他条目

**IP 拒绝列表** 阻止特定 IP 地址或范围使用此密钥，同时允许其他所有地址。

1. 点击 **+（加号）** 用于添加条目的图标
2. 输入要阻止的 IP 地址或 CIDR 范围
3. 勾选复选框以启用该条目

{% hint style="info" %}
**允许列表与拒绝列表的优先级**

当两个列表都已配置时，IP 允许列表具有优先级。如果某个地址同时出现在两个列表中，则由允许列表决定访问权限。
{% endhint %}

### 保存并获取 API 密钥

1. 检查所有设置是否正确
2. 点击 **提交** 以生成 API 密钥

弹出窗口会显示生成的 API 密钥，并提供两个选项：

* **复制**：单击可将完整密钥字符串复制到剪贴板
* **保存**：单击可将密钥下载为 `.PAK` （受保护的 API 密钥）文件

{% hint style="danger" %}
**一次性显示**

完整的 API 密钥只会在创建时显示。关闭此弹出窗口后，就无法再取回完整密钥。如果您丢失了该密钥，必须将其删除并重新创建。
{% endhint %}

在妥善保管密钥后，关闭弹出窗口。新的 API 密钥将显示在 API 密钥表中。

## 管理现有 API 密钥

### 编辑 API 密钥

1. 在 API 密钥表中，找到您要修改的密钥
2. 点击 **编辑** 旁边的（铅笔）图标
3. 更新设置（名称、描述、过期时间、IP 列表）
4. 点击 **提交** 以保存更改

{% hint style="info" %}
**密钥字符串无法更改**

编辑 API 密钥只会更新其元数据和访问控制。实际的密钥字符串无法修改。要更改密钥字符串，必须创建新的 API 密钥并删除旧密钥。
{% endhint %}

### 删除 API 密钥

1. 在 API 密钥表中，找到您要移除的密钥
2. 点击 **删除** 旁边的（垃圾桶）图标
3. 确认删除

{% hint style="warning" %}
**立即吊销**

删除 API 密钥会立即吊销所有访问权限。任何使用已删除密钥的应用程序或脚本都将认证失败。
{% endhint %}

## 使用 API 密钥

### 认证格式

API 密钥在 HTTP Authorization 头中作为 Bearer 令牌使用：

```
Authorization: Bearer <your-api-key-string>
```

### API 请求示例

```bash
curl -X GET "https://your-vergeos-instance/api/v4/system" \\
  -H "Authorization: Bearer your-api-key-string-here" \\
  -H "Content-Type: application/json"
```

### 环境变量存储

为安全起见，请从环境变量加载 API 密钥，而不是将其硬编码：

```bash
# 设置环境变量
export VERGEOS_API_KEY="your-api-key-string"

# 在 API 请求中使用
curl -X GET "https://your-vergeos-instance/api/v4/system" \\
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"
```

## 安全注意事项

**将 API 密钥视为密码** API 密钥会以关联用户的身份提供完整认证。请像保护密码一样谨慎保护它们。

**使用 IP 限制** 尽可能配置 IP 允许列表，以限制密钥可被使用的位置。这会在密钥泄露时显著降低风险。

**设置到期日期** 尽量避免使用永久密钥。定期过期可强制轮换密钥并限制暴露窗口。

**监控密钥使用情况** 定期检查“上次登录”和“上次登录 IP”字段，以识别异常访问模式。

**删除未使用的密钥** 移除不再需要的 API 密钥，以尽量缩小攻击面。

## 故障排除

**API 密钥认证失败**

确认密钥已作为 Bearer 令牌正确包含在 Authorization 头中。检查是否有多余空格或截断。

**有效密钥被拒绝访问**

检查 IP 允许/拒绝列表。您的来源 IP 可能未被允许，或者位于拒绝列表中。

**密钥已过期**

检查 API 密钥表中的“Expires”列。如果旧密钥已过期，请创建新密钥。

**无法找回丢失的密钥**

API 密钥在初始创建弹出窗口关闭后无法恢复。删除丢失的密钥并创建新密钥。

## 相关资源

* [VergeOS REST API 文档](/knowledge-base/zh/automation-api/verge-api-guide.md) - 完整的 API 参考和端点


---

# 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/zh/gong-xiang-guan-li-jie-mian/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.