API 密钥管理

API 密钥管理界面提供了一个 基于网页的用户界面，用于创建、监控和管理用于程序化访问 OmniCRM API 的 API 密钥。

::: note ::: title 注意 :::

有关一般 API 身份验证概念和使用示例，请参见 concepts_api。 :::

概述

API 密钥使 安全、长期的身份验证 成为可能，适用于：

服务器到服务器的集成
自动化脚本
第三方应用程序
定时任务和 cron 作业
外部监控系统

与 JWT 令牌（在几分钟/小时后过期）不同，API 密钥在手动撤销或到期之前始终有效。

访问 API 密钥管理

导航至：

或直接：

所需权限： MANAGE_API_KEYS（管理员角色）

API 密钥列表视图

主页面以表格格式显示所有 API 密钥：

列：

名称 - API 密钥的描述性标签（例如，“配置系统”，“监控工具”）
创建者 - 创建密钥的用户的用户名
API 密钥 - 实际的密钥字符串（出于安全原因部分隐藏）
状态 - 活动、过期或已撤销
创建日期 - 密钥生成的时间
到期日期 - 密钥将自动过期的时间
操作 - 编辑、删除、重新生成按钮

示例显示：

仪表板小部件

在页面顶部显示摘要统计信息：

总 API 密钥 - 所有 API 密钥的计数（活动和非活动）
活动密钥 - 当前有效的密钥
即将到期 - 在接下来的 30 天内到期的密钥
过期密钥 - 超过到期日期的密钥

创建 API 密钥

步骤 1：点击“添加 API 密钥”

点击 API 密钥列表右上角的 + 添加 按钮。

步骤 2：填写详细信息

会出现一个模态表单请求：

名称：________________________

: （例如，“配置系统”）

描述：__________________

: （可选 - 此密钥的目的）

到期日期：[日期选择器]

: （可选 - 留空表示没有到期）

权限：☐ 查看客户 ☐ 创建客户 ☐ 查看服务 ☐ 创建服务 ☐ 配置 ☐ 查看库存 ☑ 管理员（所有权限）

[取消] [生成密钥]

字段指南：

名称（必填）

短的描述性标识符
示例：“配置系统”，“计费集成”，“监控”
用于审计日志并在列表中显示

描述（可选）

更详细的说明
示例：“由 Ansible 配置服务器使用”，“第三方计费同步”
帮助未来的管理员理解密钥的目的

到期日期（可选）

如果留空：密钥永不失效（不推荐）
如果设置：密钥在此日期后自动失效
推荐：出于安全考虑设置到期（90 天至 1 年）

权限

选择特定权限或勾选“管理员”以获得完全访问权限
遵循与用户帐户相同的基于角色的权限模型
最佳实践： 分配最低必要权限

步骤 3：生成并复制密钥

点击 “生成密钥” 后，系统会显示新创建的 API 密钥：

⚠️ 现在复制此密钥 - 以后将不再显示！

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

[复制到剪贴板]

[关闭]

::: warning ::: title 警告 :::

请立即保存 API 密钥！

一旦关闭此对话框，无法再次检索完整密钥。您在列表视图中只会看到一个隐藏版本（sk_live_...XYZ）。

如果您丢失了密钥，您必须 重新生成 它，这将使旧密钥失效，并可能破坏现有的集成。 :::

步骤 4：配置您的��用程序

在您的应用程序请求中使用 API 密钥：

curl -X GET "https://yourcrm.com/crm/customers" \
  -H "X-API-KEY: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

或在环境变量中：

export CRM_API_KEY="sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

管理现有密钥

查看密钥详细信息

点击任何 API 密钥名称以查看完整详细信息：

完整密钥名称和描述
创建时间戳
创建者用户名
关联的权限
使用统计信息（如果已实现）
最近的访问日志

重新生成 API 密钥

如果 API 密钥被泄露或丢失，请重新生成它：

点击操作列中的 ⋮（三个点）
选择 “重新生成密钥”
确认操作

::: warning ::: title 警告 :::

重新生成会立即使旧密钥失效。

任何使用旧密钥的应用程序将停止工作。在重新生成之前，请使用新密钥更新所有集成。 :::

发生的事情：

旧密钥被撤销
生成具有相同权限的新密钥
显示新密钥（立即复制）
名称、描述和权限保持不变

撤销（删除）API 密钥

要永久删除 API 密钥：

点击操作列中的 ⋮（三个点）
选择 “删除”
确认删除

发生的事情：

密钥立即被撤销
所有使用此密钥的请求返回 401 Unauthorized
密钥从数据库中移除
无法撤销 - 密钥无法恢复

何时撤销：

集成不再需要
密钥已被泄露
使用该密钥的系统已退役
用具有不同权限的新密钥替换

编辑 API 密钥详细信息

要修改 API 密钥的详细信息：

点击操作列中的 ⋮（三个点）
选择 “编辑”
更新名称、描述、到期或权限
点击 “保存更改”

可编辑字段：

名称
描述
到期日期
权限

不可编辑：

密钥值本身（使用重新生成来更改）
创建日期
创建者用户

API 密钥状态

API 密钥可以有几种状态：

活动

密钥有效且可以使用
在到期日期内（或未设置到期）
未手动撤销
显示为绿色徽章

即将到期

活动但将在接下来的 30 天内到期
显示为橙色/警告徽章
考虑在到期前进行轮换

过期

超过到期日期
不再接受身份验证
显示为红色徽章
可以删除或延长到期

已撤销

手动删除/禁用
永久无效
不再显示在活动��表中

过滤和搜索

API 密钥列表支持：

搜索：

按名称、描述或部分密钥搜索：

按状态过滤：

过滤下拉菜单显示：

所有密钥
仅活动
即将到期（接下来的 30 天）
过期

排序：

点击列标题按以下内容排序：

名称
创建日期
到期日期
创建者

安全最佳实践

API 密钥生成

长度： 密钥应至少为 32 个字符（系统强制执行）
随机性： 使用加密安全的随机数生成器生成
格式： 通常以前缀（例如，sk_live_）进行标识

API 密钥存储

在 CRM 中：

密钥在存储前被哈希（类似于密码）
完整密钥仅在创建时显示一次
数据库存储哈希以进行验证
即使是管理员也无法在之后检索完整密钥

在您的应用程序中：

存储在环境变量中，而不是代码中
使用秘密管理系统（AWS Secrets Manager、HashiCorp Vault）
永远不要将密钥提交到版本控制
定期轮换密钥（90-365 天）

权限管理

最小权限原则 - 仅授予必要的权限
除非绝对必要，否则避免创建管理员密钥
对于不同的系统/目的使用单独的密钥
定期审查��限

监控和审计

通过活动日志监控 API 密钥使用情况
设置异常访问模式的警报
定期审查“最后使用”时间戳
删除未使用的密钥

密钥轮换

建立密钥轮换政策：

创建新密钥，权限相同
更新应用程序以使用新密钥
监控以确保旧密钥不再使用
在宽限期后撤销旧密钥

故障排除

使用 API 密钥时出现“401 Unauthorized”

原因： 密钥无效、过期或不正确
修复：
- 验证密钥是否正确复制（没有额外空格）
- 检查密钥状态（活动与过期）
- 确认密钥具有所需权限
- 确保使用 X-API-KEY 头（而不是 Authorization）

创建后出现“未找到 API 密钥”

原因： 密钥可能已创建但未正确存储
修复：
- 检查 API 密钥列表以查找新条目
- 如果缺失，请创建新密钥
- 向管理员报告问题

API 密钥即将到期

原因： 到期日期临近（30 天内）
修复：
- 创建具有延长期限的新密钥
- 更新应用程序以使用新密钥
- 在迁移后撤销旧密钥

无法删除 API 密钥

原因： 可能被保护或正在使用
修复：
- 确保您具有管理员权限
- 检查密钥是否被锁定/保护
- 如果问题仍然存在，请联系管理员

API 端点（用于程序化管理）

API 密钥也可以通过 API 管理（需要管理员权限）：

列出 API 密钥

GET /crm/api-keys
Authorization: Bearer <admin-token>

创建 API 密钥

POST /crm/api-keys
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "New Integration",
  "description": "Third-party billing sync",
  "expiry_date": "2026-01-10",
  "permissions": ["view_customer", "view_service"]
}

响应：

{
  "api_key_id": 123,
  "name": "New Integration",
  "api_key": "sk_live_a1b2c3d4e5f6g7h8i9j0",
  "status": "active",
  "created": "2025-01-10T10:00:00Z",
  "expiry_date": "2026-01-10T23:59:59Z"
}

撤销 API 密钥

DELETE /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>

更新 API 密钥

PATCH /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Updated Name",
  "expiry_date": "2026-12-31"
}

常见用例

用例 1：配置系统集成

为您的 Ansible 配置服务��创建一个 API 密钥：

导航至 API 密钥 → 添加
名称：“Ansible Provisioning Server”
描述：“由配置自动化使用”
权限：配置、查看/创建服务、查看/更新库存
到期：1 年
复制密钥并添加到 Ansible crm_config.yaml

用例 2：第三方计费集成

为计费导出创建只读密钥：

名称：“Billing Sync - QuickBooks”
权限：查看客户、查看交易、查看发票
到期：90 天（每季度轮换）
在定时导出脚本中使用

用例 3：监控和警报

为 Prometheus/Grafana 指标收集创建密钥：

名称：“Monitoring - Grafana”
权限：查看服务、查看配置
到期：永不（监控需要持续访问）
在 Grafana 数据源中配置

用例 4：客户门户 API

为客户自助服务门户创建密钥：

名称：“Customer Portal Backend”
权限：查看自己的客户、查看自己的服务、创建付款
到期：180 天
在门户后端 API 调用中使用

概述​

访问 API 密钥管理​

API 密钥列表视图​

仪表板小部件​

创建 API 密钥​

管理现有密钥​

查看密钥详细信息​

重新生成 API 密钥​

撤销（删除）API 密钥​

编辑 API 密钥详细信息​

API 密钥状态​

过滤和搜索​

安全最佳实践​

API 密钥生成​

API 密钥存储​

权限管理​

监控和审计​

密钥轮换​

故障排除​

API 端点（用于程序化管理）​

常见用例​

相关文档​

概述