> 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/zh/xi-tong-guan-li/api-keys.md).

# API 密钥

## 概述

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

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

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

## 了解 API 密钥身份验证

VergeOS 中的 API 密钥作为 Bearer 令牌，位于 HTTP Authorization 标头中。与 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 密钥作为 Bearer 令牌用于 HTTP Authorization 标头中：

```
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 密钥身份验证失败**

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

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

检查 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/run-the-platform/zh/xi-tong-guan-li/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.