跳到主要内容

API 密钥

API 密钥用于在没有交互式会话的情况下自动化 cert-ctrl。它们绑定到用户并带有明确的权限，通过 Authorization: Bearer（或 Git 的 Basic 认证）进行鉴权。服务端接受密钥后，请求将继承密钥所属用户的权限。

重要提示：API 密钥是 bearer secret，请像密码一样保护，定期轮换并及时删除不再使用的密钥。

1. 创建密钥​

多数用户在 Web 控制台创建。也可以通过 REST API 创建。

请求

POST /apiv1/users/:user_id/apikeys 或 POST /apiv1/me/apikeys

{
  "name": "ci-bot",
  "expires_in_seconds": 86400,
  "permissions": [
    {"obtype": "certificates", "obid": "123", "actions": ["read", "issue"]},
    {"obtype": "devices", "obid": "*", "actions": ["read"]}
  ]
}

说明

  • 必须提供 expires_in_seconds。
  • 响应中的 token 只会返回一次，请立即保存。
  • 权限范围目录见 GET /apiv1/permissions/catalog。
  • ACME 账户权限名称为 acme_accounts（下划线）。

2. 权限模型​

每条权限包含：

  • obtype：作用域名称（例如 certificates、devices、acme_accounts）
  • obid：* 或具体对象 id
  • actions：允许的动作（例如 read、write、issue）

安装配置自动化使用 ForInstallConfigUpdate 作用域，动作需要包含 update。

3. 认证请求​

REST / JSON 客户端​

curl -H "Authorization: Bearer ak_yourtoken" \
  https://cjj365.cc/apiv1/users/42/certificates

Git（Basic 认证）​

# Username prompt: automation-bot
# Password prompt: ak_yourtoken
git clone https://cjj365.cc/git/example/private-repo.git

4. 常见自动化流程​

给设备分配证书（仅 API Key）​

POST /apiv1/me/certificate-assign 会从 API Key 权限中推导证书 id（certificates + read）。请求体只包含 device_public_id。

curl -X POST https://cjj365.cc/apiv1/me/certificate-assign \
  -H "Authorization: Bearer ak_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{"device_public_id":"dev_abc123"}'

更新设备安装配置（仅 API Key）​

POST /apiv1/me/install-config-update/:device_public_id 需要 ForInstallConfigUpdate 权限。

curl -X POST https://cjj365.cc/apiv1/me/install-config-update/dev_abc123 \
  -H "Authorization: Bearer ak_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{"patches":[{"ob_type":"cert","ob_id":10,"enabled":true}]}'

5. 通过 API 管理密钥​

方法路径说明
GET/apiv1/users/:user_id/apikeys列出密钥（支持 offset / limit）。
GET/apiv1/users/:user_id/apikeys/:apikey_id获取单个密钥元数据。
POST/apiv1/users/:user_id/apikeys创建密钥（返回一次性 token）。
PATCH/apiv1/users/:user_id/apikeys/:apikey_id替换权限。
DELETE/apiv1/users/:user_id/apikeys/:apikey_id撤销密钥。

/apiv1/me/apikeys 作为当前会话用户的别名路径。

最佳实践​

  • 最小权限：按集成场景拆分密钥并限制权限。
  • 短生命周期：缩短有效期并自动轮换。
  • 监控审计：定期检查使用情况并及时吊销。

故障排查​

使用 API Key 常见错误码：

Code含义处理方式
4001资源不存在确认资源属于该用户。
4003无权限调整权限或更换密钥。
401未授权密钥过期/被删除/格式错误。
5000服务器错误重试或联系支持。

如果鉴权失败，错误信息中可能包含 api key lacks required permissions 或 invalid token。