API 密钥

API 密钥允许外部脚本、自动化工具或自定义应用程序与 PasarGuard 面板 API 进行通信。每个 API 密钥都绑定到特定的管理员帐户，可以选择继承该管理员的当前权限，或者使用自定义的权限限制。

创建 API 密钥

1. 前往面板侧边栏的 API 密钥。
2. 点击 创建 API 密钥。
3. 输入具有描述性的 名称（例如：计费系统同步）。
4. 选择此密钥用于认证的 管理员 帐户。
5. 提供可选的 备注 以记录密钥的用途。
6. 配置权限：
   • 继承管理员权限：启用此开关以自动使用拥有者管理员的当前角色权限。
   • 自定义权限：关闭此开关，手动配置该密钥对特定资源的具体操作范围和操作（读取、创建、更新、删除）。
7. 如果密钥在一定期限后需要失效，请设置可选的 过期日期。
8. 点击 保存。
9. 复制 API 密钥：生成的密钥密文仅显示一次。请立即复制并妥善保存在安全的密码管理器或配置文件中。它无法被找回或再次显示。

操作

• 编辑：修改密钥的名称、备注、权限配置、过期日期，或切换其状态（活动/禁用）。
• 吊销并重新签发：立即吊销当前的密钥密文，并为相同的配置生成一个新的密钥。如果密钥泄露或需要定期轮换，请使用此选项。
• 删除：永久删除该 API 密钥记录。此后任何使用此密钥的请求都将立即返回未授权错误。
• 批量删除：选择多个 API 密钥并一并删除，以清理无效或非活动的集成凭据。

安全最佳实践

• 最小权限原则：尽可能禁用“继承管理员权限”，只指定 API 密钥所需的精确权限范围。
• 设置过期时间：为临时集成设置过期日期，以最大程度地减少由于凭据泄漏带来的安全窗口期。
• 使用密钥 ID 进行监控：每个 API 密钥在列表中都有一个唯一的密钥 ID (Key ID)。使用此 ID 可以在服务器日志中识别特定的密钥，而无需暴露实际的密钥密文。
• 禁用不活跃的密钥：如果某个 API 密钥当前不使用，可将其状态修改为 禁用 而非直接删除，以便日后需要时能随时重新启用。

使用 API 密钥

您可以通过在 HTTP 请求中发送该密钥来对面板的 REST API 进行身份验证，支持以下两种方式之一：

1. 自定义 HTTP 请求头（推荐）

在 HTTP 请求的 X-Api-Key 请求头中包含该密钥：

curl -H "X-Api-Key: pg_key_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
     https://your-panel-domain/api/admin/users

2. Authorization 请求头

或者，使用标准的 Authorization 请求头并带上 apikey 前缀：

curl -H "Authorization: apikey pg_key_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
     https://your-panel-domain/api/admin/users