接口详情
GET /v1/certificate-assets
List active certificate assets
- operationId
listCertificateAssets- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.read
说明（契约原文）
Tenant sessions target their own scope. Platform sessions retain their platform actor scope. Only this collection GET may omit target_scope_id to list assets across active tenants, with live certificates.read authorization. An explicit target limits the collection to that tenant. Detail and write operations still require an explicit platform target.
参数
listCertificateAssets 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
search | query | string | 否 | — |
|---|
status | query | string: normal / expiring / expired / auto_renew / manual_renew | 否 | normal/expiring/expired by the latest version (expiring: active or default and expiring within 30 days; expired: not_after passed); auto_renew/manual_renew by whether an auto-renewing order issued the asset. |
|---|
domain | query | string | 否 | Advanced search (CERT-05); every advanced filter narrows items, total and counts alike. A SAN of any version contains it, case-insensitive. |
|---|
domains | query | string | 否 | Comma-separated domains; the latest version's SANs contain every one exactly (case-insensitive). At most 100. |
|---|
user | query | string | 否 | The recorded owner's display ID, username, email or phone contains it. |
|---|
certificate_id | query | string | 否 | The asset display ID contains it. |
|---|
name | query | string | 否 | — |
|---|
remark | query | string | 否 | — |
|---|
source | query | string: uploaded / acme | 否 | — |
|---|
dns_provider_id | query | string(uuid) | 否 | The DNS provider of the order that issued the asset. |
|---|
expiry | query | string: within30 / within90 / expired | 否 | within30/within90 are latest versions in force (active or default, not expired) expiring within 30/90 days; expired is a passed not_after. Expired assets are never within30/within90. |
|---|
auto_renew | query | string: true / false | 否 | Whether an auto-renewing order issued the asset. |
|---|
issue | query | string: issued / failed | 否 | issued is an asset issued by an order; failed is an asset whose issuing order or one of its renewal orders failed. |
|---|
sync | query | string: complete / pending / failed | 否 | Publication of the asset's current site bindings; failed when one permanently failed, complete when every one succeeded and its apply rollout has every node deployment healthy, pending otherwise. An unbound asset matches none. |
|---|
X-Request-ID | header | string | 否 | — |
|---|
响应
listCertificateAssets 响应| 状态码 | 说明 |
|---|
200 | Certificate assets 字段：items: array<CertificateAsset> total: integer(int64) counts: object |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
405 | Method not allowed |
|---|
500 | Sanitized internal failure |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/certificate-assets
Upload a certificate and private key
- operationId
uploadCertificateAsset- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.manage
说明（契约原文）
Requires certificates.manage. The private key crosses this request boundary once, is encrypted by the certificate store, and is never returned in a response. Exact replay uses the same request body, X-Request-ID and Idempotency-Key without adding facts. owner_user_id records an active member of the target tenant and is immutable. Tenant uploads default to the actor and cannot assign another user. For compatibility, platform clients may omit owner_user_id; these assets remain legacy_unknown. The admin UI requires explicit ownership. Omitted-owner legacy requests retain their original idempotency digest and receipt ownership.
参数
uploadCertificateAsset 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | Retry an unknown result only with this exact key and unchanged request. |
|---|
请求体
application/json · 必填：是
uploadCertificateAsset 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
owner_user_id | string(uuid) | 否 | Active target-tenant member. Immutable after creation. Tenant actors may only select themselves; omitted platform ownership stays unknown for legacy clients. |
|---|
name | string | 是 | — |
|---|
remark | string | 否 | Optional; trimmed, no control characters. Part of the idempotency digest. |
|---|
certificate_pem | string | 是 | — |
|---|
private_key_pem | string | 是 | Never returned by this API. |
|---|
响应
uploadCertificateAsset 响应| 状态码 | 说明 |
|---|
201 | Certificate asset created or exactly replayed 字段：asset: CertificateAsset versions: array<CertificateAssetVersion> |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
405 | Method not allowed |
|---|
409 | Revision, idempotency, reference or lifecycle conflict |
|---|
413 | Request body exceeds 384 KiB |
|---|
415 | Content-Type is not application/json with optional UTF-8 charset |
|---|
500 | Sanitized internal failure |
|---|
503 | Certificate private-key envelope service unavailable |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/certificate-assets/{asset_id}
Get a certificate asset and its public versions
- operationId
getCertificateAsset- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.read
说明（契约原文）
Private-key plaintext, ciphertext and envelope metadata are never returned.
参数
getCertificateAsset 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
asset_id | path | string(uuid) | 是 | — |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
X-Request-ID | header | string | 否 | — |
|---|
响应
getCertificateAsset 响应| 状态码 | 说明 |
|---|
200 | Certificate asset detail 字段：asset: CertificateAsset versions: array<CertificateAssetVersion> |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
404 | Certificate asset or version not found |
|---|
405 | Method not allowed |
|---|
500 | Sanitized internal failure |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
DELETE /v1/certificate-assets/{asset_id}
Soft-delete an unreferenced certificate asset
- operationId
deleteCertificateAsset- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.manage
参数
deleteCertificateAsset 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
asset_id | path | string(uuid) | 是 | — |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | Retry an unknown result only with this exact key and unchanged request. |
|---|
请求体
application/json · 必填：是
deleteCertificateAsset 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
响应
deleteCertificateAsset 响应| 状态码 | 说明 |
|---|
200 | Certificate asset 字段：id: string(uuid) display_id: string tenant_scope_id: string(uuid) tenant: CertificateAssetTenant owner: CertificateAssetOwner | null owner_status: string: recorded / legacy_unknown name: string remark?: string source: string: uploaded / acme auto_renew: boolean disabled: boolean revision: integer(int64) created_by: string(uuid) created_by_display_id: string updated_by: string(uuid) updated_by_display_id: string created_at: string(date-time) updated_at: string(date-time) deleted_at?: string(date-time) |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
404 | Certificate asset or version not found |
|---|
405 | Method not allowed |
|---|
409 | Revision, idempotency, reference or lifecycle conflict |
|---|
413 | Request body exceeds 384 KiB |
|---|
415 | Content-Type is not application/json with optional UTF-8 charset |
|---|
500 | Sanitized internal failure |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PATCH /v1/certificate-assets/{asset_id}/auto-renew
Turn automatic renewal of an ACME certificate on or off
- operationId
setCertificateAssetAutoRenew- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.manage
说明（契约原文）
Renewal intent lives on the certificate asset; the issuing order's auto_renew stays an immutable snapshot. Uploaded certificates return 409 certificate_asset_auto_renew_unsupported. Audited as certificate.auto_renew.update.
参数
setCertificateAssetAutoRenew 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
asset_id | path | string(uuid) | 是 | — |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | Retry an unknown result only with this exact key and unchanged request. |
|---|
请求体
application/json · 必填：是
setCertificateAssetAutoRenew 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
enabled | boolean | 是 | — |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
响应
setCertificateAssetAutoRenew 响应| 状态码 | 说明 |
|---|
200 | Certificate asset 字段：id: string(uuid) display_id: string tenant_scope_id: string(uuid) tenant: CertificateAssetTenant owner: CertificateAssetOwner | null owner_status: string: recorded / legacy_unknown name: string remark?: string source: string: uploaded / acme auto_renew: boolean disabled: boolean revision: integer(int64) created_by: string(uuid) created_by_display_id: string updated_by: string(uuid) updated_by_display_id: string created_at: string(date-time) updated_at: string(date-time) deleted_at?: string(date-time) |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
404 | Certificate asset or version not found |
|---|
405 | Method not allowed |
|---|
409 | Revision, idempotency, reference or lifecycle conflict |
|---|
413 | Request body exceeds 384 KiB |
|---|
415 | Content-Type is not application/json with optional UTF-8 charset |
|---|
500 | Sanitized internal failure |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/certificate-assets/{asset_id}/bindings
List current site bindings for one certificate asset
- operationId
listCertificateAssetBindings- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.read
参数
listCertificateAssetBindings 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
asset_id | path | string(uuid) | 是 | — |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
X-Request-ID | header | string | 否 | — |
|---|
响应
listCertificateAssetBindings 响应| 状态码 | 说明 |
|---|
200 | Current certificate asset bindings 字段：items: array<CertificateAssetBinding> |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
404 | Certificate asset or version not found |
|---|
405 | Method not allowed |
|---|
500 | Sanitized internal failure |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/certificate-assets/{asset_id}/bindings
Bind an active version to a tenant site
- operationId
bindCertificateAsset- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.manage
参数
bindCertificateAsset 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
asset_id | path | string(uuid) | 是 | — |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | Retry an unknown result only with this exact key and unchanged request. |
|---|
请求体
application/json · 必填：是
bindCertificateAsset 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
site_id | string(uuid) | 是 | — |
|---|
version_id | string(uuid) | 是 | — |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
default | boolean | 是 | — |
|---|
响应
bindCertificateAsset 响应| 状态码 | 说明 |
|---|
200 | Current binding fact 字段：tenant_scope_id: string(uuid) site_id: string(uuid) asset_id: string(uuid) version_id: string(uuid) revision: integer(int64) default: boolean bound: boolean changed_by: string(uuid) changed_at: string(date-time) |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
404 | Certificate asset or version not found |
|---|
405 | Method not allowed |
|---|
409 | Revision, idempotency, reference or lifecycle conflict |
|---|
413 | Request body exceeds 384 KiB |
|---|
415 | Content-Type is not application/json with optional UTF-8 charset |
|---|
500 | Sanitized internal failure |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
DELETE /v1/certificate-assets/{asset_id}/bindings/{site_id}
Append an immutable site unbind fact
- operationId
unbindCertificateAsset- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.manage
参数
unbindCertificateAsset 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
asset_id | path | string(uuid) | 是 | — |
|---|
site_id | path | string(uuid) | 是 | — |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | Retry an unknown result only with this exact key and unchanged request. |
|---|
请求体
application/json · 必填：是
unbindCertificateAsset 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
响应
unbindCertificateAsset 响应| 状态码 | 说明 |
|---|
200 | Current binding fact 字段：tenant_scope_id: string(uuid) site_id: string(uuid) asset_id: string(uuid) version_id: string(uuid) revision: integer(int64) default: boolean bound: boolean changed_by: string(uuid) changed_at: string(date-time) |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
404 | Certificate asset or version not found |
|---|
405 | Method not allowed |
|---|
409 | Revision, idempotency, reference or lifecycle conflict |
|---|
413 | Request body exceeds 384 KiB |
|---|
415 | Content-Type is not application/json with optional UTF-8 charset |
|---|
500 | Sanitized internal failure |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PATCH /v1/certificate-assets/{asset_id}/disabled
Disable or re-enable a certificate
- operationId
setCertificateAssetDisabled- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.manage
说明（契约原文）
fix-certops. A disabled certificate cannot be bound to a site and is not auto-renewed. A certificate still bound to a site returns 409 certificate_asset_referenced; binding a disabled one returns 409 certificate_asset_disabled. Audited as certificate.asset.disable / certificate.asset.enable.
参数
setCertificateAssetDisabled 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
asset_id | path | string(uuid) | 是 | — |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | Retry an unknown result only with this exact key and unchanged request. |
|---|
请求体
application/json · 必填：是
setCertificateAssetDisabled 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
disabled | boolean | 是 | — |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
响应
setCertificateAssetDisabled 响应| 状态码 | 说明 |
|---|
200 | Certificate asset 字段：id: string(uuid) display_id: string tenant_scope_id: string(uuid) tenant: CertificateAssetTenant owner: CertificateAssetOwner | null owner_status: string: recorded / legacy_unknown name: string remark?: string source: string: uploaded / acme auto_renew: boolean disabled: boolean revision: integer(int64) created_by: string(uuid) created_by_display_id: string updated_by: string(uuid) updated_by_display_id: string created_at: string(date-time) updated_at: string(date-time) deleted_at?: string(date-time) |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
404 | Certificate asset or version not found |
|---|
405 | Method not allowed |
|---|
409 | Revision, idempotency, reference or lifecycle conflict |
|---|
413 | Request body exceeds 384 KiB |
|---|
415 | Content-Type is not application/json with optional UTF-8 charset |
|---|
500 | Sanitized internal failure |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/certificate-assets/{asset_id}/download
Download the current certificate version with its private key
- operationId
downloadCertificateAsset- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.manage
说明（契约原文）
fix-certops 下载证书. A zip with fullchain.pem (certificate chain) and privkey.pem (PKCS#8 PEM) of the latest activated version. Requires certificates.manage; a tenant downloads only its own certificates. Audited as certificate.asset.download in the same transaction before the key is returned. A revoked current version returns 409 certificate_asset_download_unavailable.
参数
downloadCertificateAsset 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
asset_id | path | string(uuid) | 是 | — |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
响应
downloadCertificateAsset 响应| 状态码 | 说明 |
|---|
200 | Certificate zip (Content-Disposition attachment, named after the primary domain). |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
404 | Certificate asset or version not found |
|---|
405 | Method not allowed |
|---|
409 | Revision, idempotency, reference or lifecycle conflict |
|---|
500 | Sanitized internal failure |
|---|
503 | Private key envelope unavailable (certificate_asset_envelope_unavailable) |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/certificate-assets/{asset_id}/versions/{version_id}/activate
Atomically activate one immutable certificate version
- operationId
activateCertificateAssetVersion- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：certificates.manage
参数
activateCertificateAssetVersion 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
asset_id | path | string(uuid) | 是 | — |
|---|
version_id | path | string(uuid) | 是 | — |
|---|
target_scope_id | query | string(uuid) | 否 | Required for platform detail and write operations; optional for the collection GET to list active tenants. Forbidden when it differs from a tenant actor scope. |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | Retry an unknown result only with this exact key and unchanged request. |
|---|
请求体
application/json · 必填：是
activateCertificateAssetVersion 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
响应
activateCertificateAssetVersion 响应| 状态码 | 说明 |
|---|
200 | Certificate asset version 字段：id: string(uuid) asset_id: string(uuid) tenant_scope_id: string(uuid) version: integer(int64) status: string: default / pending_activation / active / superseded / revoked / expired fingerprint_sha256: string certificate_pem: string(byte) sans: array<string> subject: string serial_number: string public_key_algorithm: string public_key_bits: integer signature_algorithm: string not_before: string(date-time) not_after: string(date-time) acme_order_id?: string(uuid) renewal_due_at?: string(date-time) renewal_due: boolean imported_by: string(uuid) imported_at: string(date-time) |
|---|
400 | Invalid request, metadata or certificate material |
|---|
401 | Bearer session missing or invalid |
|---|
403 | Tenant scope or live permission denied |
|---|
404 | Certificate asset or version not found |
|---|
405 | Method not allowed |
|---|
409 | Revision, idempotency, reference or lifecycle conflict |
|---|
413 | Request body exceeds 384 KiB |
|---|
415 | Content-Type is not application/json with optional UTF-8 charset |
|---|
500 | Sanitized internal failure |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表