API reference
/v1/certificate-orders2 operations
← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures
| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | /v1/certificate-orders | List certificate orders | Session |
| POST | /v1/certificate-orders | Queue a pending certificate order | Session |
Contract file：api/openapi/v1/dns-acme.yaml
/v1/certificate-ordersList certificate orders
| Status | Description |
|---|---|
200 | Orders visible in the authenticated scope. Fields： |
401 | Authentication is required. |
403 | The active role lacks the required permission. |
401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account./v1/certificate-ordersQueue a pending certificate order
Wildcards require dns-01 and a provider in the same tenant scope. A 202 response only persists a tenant-scoped pending intent and its audit event; it does not claim CA acceptance. Reusing an Idempotency-Key with a different scope, domain set, challenge, provider, or auto-renew value returns a conflict. HTTP-01 forbids dns_provider_id; DNS-01 requires a verified same-tenant provider. Entitlement authorization is a separate fail-closed server composition requirement and is not implied by RBAC.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | — |
application/json · Required：Yes
| Name | Type | Required | Description |
|---|---|---|---|
target_scope_id | string(uuid) | No | — |
dns_provider_id | string(uuid) | No | — |
domains | array<string> | Yes | — |
challenge_type | string: http-01 / dns-01 | Yes | — |
auto_renew | boolean | Yes | — |
issuer | string: lets_encrypt / zerossl / google_trust | No | The CA. Omitted uses the requesting user's default issuer, then the platform default. The resolved CA is frozen on the order and its renewals; a CA without platform EAB credentials is refused with 409 certificate_issuer_unavailable. An order for the same domain set that is still pending, validating or issuing refuses the new order with 409 certificate_order_in_flight. |
name | string | No | Names the order and the certificate it issues; trimmed. |
remark | string | No | Copied to the issued certificate; trimmed |
| Status | Description |
|---|---|
202 | Pending intent stored without external side effects. Fields： |
400 | Invalid request or structurally invalid DNS/certificate data. |
401 | Authentication is required. |
403 | The active role lacks the required permission. |
404 | Resource absent or hidden by tenant isolation. |
409 | Duplicate, referenced, stale, or conflicting idempotent request. |
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.