版本 2.4.7.20261116085428 · 最新

证书 certs

上传或自动签发的 HTTPS 证书。可绑定到站点;有站点在用时不能删除或停用。

点击任一接口,右侧显示对应的调用示例。

证书鉴权: 用户(部分参数仅管理员)14 个接口

鉴权

请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。

X-API-Key

鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。

约定

分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。

时间一律 RFC 3339(UTC);金额单位为分。

写操作成功回 200/201/204;重复提交按资源唯一键回 409。

GET/api/v2/certs列出证书

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
sortstring 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。
tenant_idinteger 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。
tenant_idsstring 仅管理员可用:只看这些租户,逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用。只做过滤、不切换请求作用域,与 tenant_id 及其他条件取交集;租户凭据带了非空值回 403。
namestring 名称包含。
domainstring SAN 包含(域名或 IP 的一部分)。
scopestring site = 站点证书;ip = 平台 IP 证书;panel = 面板证书(主控 HTTPS 监听用)。
可选值 ["site","ip","panel"]
enabledboolean 是否启用
expire_daysinteger 只列 N 天内到期(含已过期)的证书。
idinteger 证书 id 精确匹配。
idsstring 多个证书 id 逗号分隔(至多 200 个),命中其中任一个。
desstring 备注包含。
typestring 证书类型。
可选值 ["custom","lets","zerossl","zerossl_api"]
dns_api_idinteger 用此 DNS API 凭据的证书。
dns_api_idsstring 按 DNS API(多个)过滤:逗号分隔的正整数,去重后至多 200 个(超了或格式错 422);只选 1 个也可用;与其他条件取交集。
qstring 候选搜索:名称包含或域名(SAN)包含该词即命中(不分大小写,名称与域名是 OR),可与 name、domain 同用(都要满足)。
domainsstring 多个域名或 IP,逗号分隔,证书 SAN 里含其中任一个(精确匹配)。
issue_statestring ACME 签发状态(上传的证书没有)。
可选值 ["pending","running","issued","failed"]
kindstring domain = SAN 含域名;ip = SAN 全是 IP。
可选值 ["domain","ip"]
POST/api/v2/certs创建证书

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
tenant_idinteger 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。

请求体 application/json

字段类型说明
acmeCertAcmeSummary 签发状态摘要(证书 GET 与列表里带):签发得来的证书(type=lets/zerossl/zerossl_api)才有,上传的证书(custom)没有这个字段。完整状态(验证方式、ARI 窗口等)见 GET /certs/{id}/acme。
certstring 证书链 PEM(叶证书在前,补全过中间证书,不含根);不含私钥(私钥只能经 POST /certs/{id}/private-key 导出)。
desstring 备注说明
enabledboolean 是否启用
keystring 私钥 PEM(PKCS#1/PKCS#8/SEC1,不许加密);换证时不给则用原私钥核对。
name必填string 名称
scopestring 证书范围:site = 站点证书;ip = 平台 IP 证书;panel = 面板证书。
可选值 ["site","ip","panel"]
typestring custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。
GET/api/v2/certs/acme-states批量查 ACME 签发状态

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
ids必填string 证书 id,逗号分隔,至多 200 个。
POST/api/v2/certs/batch批量申请 ACME 证书

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
tenant_idinteger 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。

请求体 application/json

字段类型说明
acme_account_idinteger 指定签发账号(同 POST /certs 的 acme.acme_account_id);不给按类型先取本租户启用的、再取平台启用的。
auto_renewboolean 不给为 true。
desstring 备注说明
dns_api_idinteger DNS-01 验证用的 DNS API 凭据(ACME 证书用)。
items必填CertAcme[] 签发状态。
typestring custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。
POST/api/v2/certs/batch-issue批量重签或续签 ACME 证书

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
ids必填integer[] 证书 id。
GET/api/v2/certs/zerossl-ips列出可签 ZeroSSL 证书的 IP

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
tenant_idinteger 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。
GET/api/v2/certs/{id}获取证书

鉴权: 用户(部分参数仅管理员)

PUT/api/v2/certs/{id}修改证书

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
acmeCertAcmeSummary 签发状态摘要(证书 GET 与列表里带):签发得来的证书(type=lets/zerossl/zerossl_api)才有,上传的证书(custom)没有这个字段。完整状态(验证方式、ARI 窗口等)见 GET /certs/{id}/acme。
certstring 证书链 PEM(叶证书在前,补全过中间证书,不含根);不含私钥(私钥只能经 POST /certs/{id}/private-key 导出)。
desstring 备注说明
enabledboolean 是否启用
keystring 私钥 PEM(PKCS#1/PKCS#8/SEC1,不许加密);换证时不给则用原私钥核对。
name必填string 名称
scopestring 证书范围:site = 站点证书;ip = 平台 IP 证书;panel = 面板证书。
可选值 ["site","ip","panel"]
typestring custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。
DELETE/api/v2/certs/{id}删除证书

鉴权: 用户(部分参数仅管理员)

GET/api/v2/certs/{id}/acme获取证书的 ACME 签发状态

鉴权: 用户(部分参数仅管理员)

PUT/api/v2/certs/{id}/acme修改证书的自动续签开关

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
auto_renew必填boolean 不给为 true。
POST/api/v2/certs/{id}/bind证书绑定到站点

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
site_ids必填integer[] 在用此证书的站点。
POST/api/v2/certs/{id}/issue重新签发 ACME 证书

鉴权: 用户(部分参数仅管理员)

POST/api/v2/certs/{id}/private-key导出证书私钥

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
passwordstring 当前登录口令。
totp_codestring 动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。

证书对象

字段类型说明
acmeCertAcmeSummary 签发状态摘要(证书 GET 与列表里带):签发得来的证书(type=lets/zerossl/zerossl_api)才有,上传的证书(custom)没有这个字段。完整状态(验证方式、ARI 窗口等)见 GET /certs/{id}/acme。
只读
acme_account_idinteger 指定签发账号(同 POST /certs 的 acme.acme_account_id);不给按类型先取本租户启用的、再取平台启用的。
ari_endstring CA 经 ARI 建议的续签窗口结束时间。
ari_startstring CA 经 ARI 建议的续签窗口;null = CA 没给,按到期前 cert.acme.renew_before_days 天续签。
auto_renewboolean 不给为 true。
certstring 证书链 PEM(叶证书在前,补全过中间证书,不含根);不含私钥(私钥只能经 POST /certs/{id}/private-key 导出)。
只读
cert_idinteger 证书 id。
challengestring 验证方式:http-01、dns-01,或 http-file(zerossl_api 的 ZeroSSL 文件验证)。
可选值 ["http-01","dns-01","http-file"]
created_atstring 创建时间
只读
desstring 备注说明
dns_api_idinteger DNS-01 验证用的 DNS API 凭据(ACME 证书用)。
enabledboolean 是否启用
err_timesinteger 这一轮已失败次数。
failedinteger 失败的条数。
fingerprintstring 叶证书 SHA-256 指纹(小写十六进制)。
只读
idinteger 记录 ID
只读
ids必填integer[] 证书 id。
issued_atstring 最近一次签发成功的时间。
issuerstring 证书颁发者。
只读
itemsCertAcme[] 签发状态。
keystring 私钥 PEM(PKCS#1/PKCS#8/SEC1,不许加密);换证时不给则用原私钥核对。
last_errorstring 最近一次错误
namestring 名称
namesstring[] SAN(域名、通配域名或 IP);无 SAN 时取 CN。
只读
next_retry_atstring 失败后等退避重试(state=pending 且 err_times>0)的下次重试时刻,取自延时任务队列;其余为 null。
next_try_atstring 续签失败终态后,续签扫描最早再试的时刻。
not_afterstring 证书到期时间。
只读
not_beforestring 证书生效时间。
只读
ocspboolean 叶证书带 OCSP 地址(节点可装订)。
只读
okinteger 已排队签发的条数。
passwordstring 当前登录口令。
renewingboolean 当前这轮是续签(失败时旧证书照用)。
scopestring 证书范围:site = 站点证书;ip = 平台 IP 证书;panel = 面板证书。
可选值 ["site","ip","panel"]
site_idsinteger[] 在用此证书的站点。
只读
statestring pending 排队或等重试;running 签发中;issued 已签出;failed 重试用完(已发提醒)。
可选值 ["pending","running","issued","failed"]
tenant_idinteger 所属租户;null = 平台 IP 证书。
只读
totp_codestring 动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。
typestring custom = 上传;lets/zerossl = ACME 签发;zerossl_api = ZeroSSL 付费 REST API 签发。
updated_atstring 更新时间
只读
versioninteger 证书内容版本,换证 +1。
只读
zerossl_order_idstring zerossl_api 证书当前的 ZeroSSL 订单号;空 = 还没下单。
zerossl_order_statestring ZeroSSL 订单状态(draft、pending_validation、issued、cancelled 等);空 = 还没下单。

返回与错误

成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。

成功
{
  "id": 1,
  "name": "example"
}
列表
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
失败
{
  "code": "validation_failed",
  "detail": "请求参数不合法",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name 必填"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
开始使用

123

123