GET /v1/certificate-defaults
Read a user's certificate request defaults
- operationId
getCertificateDefaults- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：certificates.read
Description (from the contract)
The default certificate type, DNS provider and CA prefilled into a new request. A user without saved defaults reads acme with revision 0. Tenant actors read their own scope; platform actors name the target tenant scope and user.
Parameters
getCertificateDefaults Parameters| Name | In | Type | Required | Description |
|---|
target_scope_id | query | string(uuid) | No | Required for platform actors; tenant actors may only target their own scope. |
|---|
target_user_id | query | string(uuid) | No | Defaults to the authenticated user. |
|---|
Responses
getCertificateDefaults Responses| Status | Description |
|---|
200 | The user's defaults; ETag carries the revision. Fields：scope_id: string(uuid) user_id: string(uuid) certificate_type: string: acme / uploaded dns_provider_id?: string(uuid) issuer?: string: lets_encrypt / zerossl / google_trust revision: integer(int64) updated_at?: string(date-time) |
|---|
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. |
|---|
500 | Sanitized internal failure. |
|---|
What to do on failure
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.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
PATCH /v1/certificate-defaults
Save a user's certificate request defaults
- operationId
updateCertificateDefaults- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：certificates.manage
Description (from the contract)
Compare-and-set on expected_revision (version_conflict when stale). dns_provider_id must be an enabled provider in the target scope (dns_resource_conflict otherwise). issuer is a known CA that is available now: a CA without platform EAB credentials is refused with certificate_issuer_unavailable (409) when saved, the same check an order create applies; uploaded defaults drop dns_provider_id and issuer. An order that falls back to a default CA whose credentials were removed later is still refused with certificate_issuer_unavailable when it is created.
Parameters
updateCertificateDefaults Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
updateCertificateDefaults Request body| Name | Type | Required | Description |
|---|
target_scope_id | string(uuid) | No | — |
|---|
target_user_id | string(uuid) | No | — |
|---|
certificate_type | string: acme / uploaded | Yes | — |
|---|
dns_provider_id | string(uuid) | null(uuid) | No | Empty or null clears the default provider. |
|---|
issuer | string: lets_encrypt / zerossl / google_trust / / null | null: lets_encrypt / zerossl / google_trust / / null | No | Empty or null uses the platform default. |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
updateCertificateDefaults Responses| Status | Description |
|---|
200 | Saved defaults; ETag carries the new revision. Fields：scope_id: string(uuid) user_id: string(uuid) certificate_type: string: acme / uploaded dns_provider_id?: string(uuid) issuer?: string: lets_encrypt / zerossl / google_trust revision: integer(int64) updated_at?: string(date-time) |
|---|
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. |
|---|
500 | Sanitized internal failure. |
|---|
What to do on failure
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.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list