Operation details
GET /v1/site-publications
List publications in the authenticated tenant scope
- operationId
listTenantSitePublications- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- 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：sites.read
Description (from the contract)
Requires a tenant-scoped principal with sites.read. scope_id is not accepted. Signatures, hashes, target snapshot metadata, and platform scope identifiers are omitted from tenant responses.
Parameters
listTenantSitePublications Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Versioned base64url HMAC-SHA256 envelope returned by the immediately preceding page. It is bound to audience, resolved tenant scope, resource kind, and the rollout ID for deployment pages. It cannot be reused across those boundaries or modified. |
|---|
Responses
listTenantSitePublications Responses| Status | Description |
|---|
200 | Stable tenant publication page with target metadata redacted. Fields：items: array<TenantPublication> current_source_revision: integer(int64) next_cursor?: string pending_modules?: array<PendingModule> automatic_failure?: AutomaticPublicationFailure |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/site-publications
Publish the authenticated tenant scope
- operationId
publishTenantSiteConfiguration- 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：sites.manage
Description (from the contract)
Requires a tenant session with sites.manage. configuration_scope_id must exactly equal the authenticated scope; authorization and scope binding complete before any publication mutation.
Parameters
publishTenantSiteConfiguration Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
publishTenantSiteConfiguration Request body| Name | Type | Required | Description |
|---|
configuration_scope_id | string(uuid) | Yes | — |
|---|
expected_source_revision | integer(int64) | Yes | — |
|---|
target | ExplicitNodeTarget | LineGroupSnapshotTarget | Yes | — |
|---|
health_check | HealthCheck | Yes | — |
|---|
rollout | RolloutPolicyInput | No | Progressive policy for a target frozen at publication time. Nodes are ordered by UUID bytes, then assigned to the canary and fixed-size cohorts. Commands outside the released cohort remain held. The failure threshold is an absolute failed-node count within the current cohort; reaching it pauses the rollout. |
|---|
max_attempts | integer | Yes | — |
|---|
deadline | string(date-time) | Yes | Future RFC3339 deployment deadline. |
|---|
Responses
publishTenantSiteConfiguration Responses| Status | Description |
|---|
201 | Created tenant publication, or the stored result of an identical retry. Fields：id: string(uuid) source_revision: integer(int64) config_version_id: string(uuid) rollout_id: string(uuid) target: TenantPublicationTarget node_count: integer created_at: string(date-time) |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
412 | The source or rollout expected revision is stale. |
|---|
422 | Entitlement or target/resource readiness prevents publication. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.412 The revision changed: read the latest ETag, decide again, then send the new If-Match.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/site-publications/security-activations
Get the authoritative security binding and latest activation candidate
- operationId
getSecurityPolicyActivationStatus- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- 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：security_policies.read
Description (from the contract)
Requires security_policies.read in the authenticated tenant scope, or a platform session holding security_policies.read or platform.admin, which reads the site's own tenant scope (the site edit page of the platform console). When no binding exists, binding, latest_candidate, and operation are null; clients use binding and active-policy CAS values 0/0 for first publish.
Parameters
getSecurityPolicyActivationStatus Parameters| Name | In | Type | Required | Description |
|---|
site_id | query | string(uuid) | Yes | — |
|---|
policy_kind | query | string: cc / acl / waf | Yes | — |
|---|
Responses
getSecurityPolicyActivationStatus Responses| Status | Description |
|---|
200 | Authoritative binding and latest candidate from one permission-checked transaction. Fields：binding: SecurityActivationBinding | null latest_candidate: SecurityActivationCandidate | null operation: string: activation / rollback / null | null: activation / rollback / null failure_reasons?: array<object> latest_detach?: boolean rollback?: object |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/site-publications/security-activations
Stage a security policy candidate and start its canary rollout
- operationId
createSecurityPolicyActivation- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- 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：security_policies.manage
Description (from the contract)
Requires security_policies.manage in the authenticated tenant scope. A platform session holding security_policies.manage or platform.admin starts it in the site's tenant scope without switching identity; the candidate and the audit event record the platform actor, the audit event's scope is the site's tenant scope. The candidate pins one source revision, config version, signed artifact digest, and target snapshot. The active policy and source revision do not advance until every pinned target reports healthy.
Parameters
createSecurityPolicyActivation Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
createSecurityPolicyActivation Request body| Name | Type | Required | Description |
|---|
site_id | string(uuid) | Yes | — |
|---|
policy_id | string(uuid) | Yes | — |
|---|
policy_version | integer(int64) | Yes | — |
|---|
expected_binding_revision | integer(int64) | Yes | — |
|---|
expected_active_policy_version | integer(int64) | Yes | — |
|---|
target_node_ids | array<string(uuid)> | No | Omitted or empty targets the active nodes of the site's own and its package's primary/backup line groups (no_target_nodes when there are none). |
|---|
canary_size | integer | No | 0 or omitted is 1 when the targets are resolved from the site. |
|---|
expires_at | string(date-time) | Yes | At most 15 minutes ahead (activation_expiry_too_late). |
|---|
detach | boolean | No | Withdraw the site's active library of this kind (policy_id/policy_version are the binding's active ones; the library may be deleted). policy_id differing from the binding's library rebinds the site to it; a deleted library cannot be bound (security_policy_deleted). |
|---|
Responses
createSecurityPolicyActivation Responses| Status | Description |
|---|
201 | Candidate claimed and immutable canary rollout created. Fields：candidate: SecurityActivationCandidate replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
422 | Entitlement or target/resource readiness prevents publication. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/site-publications/security-activations/rebind-status
Count bound sites still behind their WAF/CC library and those the package does not entitle
- operationId
getSecurityPolicyRebindStatus- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- 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：security_policies.read
Description (from the contract)
Requires security_policies.read in the authenticated tenant scope; a platform session is refused (403), it has no tenant scope to count. A library saved without a site context is republished automatically to every bound site whose binding is behind it (the site's package primary/backup line-group nodes, canary first). pending_sites counts the scope's sites still behind for policy_kind; package_denied_sites counts those whose package does not include the feature (they are retried and publish once it is enabled).
Parameters
getSecurityPolicyRebindStatus Parameters| Name | In | Type | Required | Description |
|---|
policy_kind | query | string: waf / cc | Yes | — |
|---|
Responses
getSecurityPolicyRebindStatus Responses| Status | Description |
|---|
200 | Counts of the authenticated scope only. Fields：pending_sites: integer package_denied_sites: integer |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/site-publications/security-activations/{candidate_id}
Get a security policy activation candidate
- operationId
getSecurityPolicyActivation- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- 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：security_policies.read
Parameters
getSecurityPolicyActivation Parameters| Name | In | Type | Required | Description |
|---|
candidate_id | path | string(uuid) | Yes | — |
|---|
Responses
getSecurityPolicyActivation Responses| Status | Description |
|---|
200 | Current persisted candidate identity and status. Fields：id: string(uuid) tenant_scope_id: string(uuid) site_id: string(uuid) binding_id: string(uuid) binding_revision: integer(int64) last_bundle_id: string(uuid) last_claimed_policy_version: integer(int64) expected_active_policy_version: integer(int64) candidate_source_revision: integer(int64) candidate_config_version_id: string(uuid) candidate_artifact_sha256: array<integer> target_snapshot_sha256: array<integer> required_capabilities: array<SecurityActivationCapability> candidate_status: string: claimed / canary / expanding / healthy / failed / cancelled / expired / promoted canary_node_ids: array<string(uuid)> expand_node_ids: array<string(uuid)> expires_at: string(date-time) created_at: string(date-time) updated_at: string(date-time) recovered_at?: string(date-time) |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/site-publications/security-activations/{candidate_id}/reconcile
Reconcile canary, expansion, recovery, and promotion
- operationId
reconcileSecurityPolicyActivation- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- 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：security_policies.manage
Description (from the contract)
Reuses the candidate config and artifact digest for every phase. Promotion uses the complete expected active, binding, publication, config, artifact, source revision, and target snapshot CAS identity.
Parameters
reconcileSecurityPolicyActivation Parameters| Name | In | Type | Required | Description |
|---|
candidate_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
reconcileSecurityPolicyActivation Request body| Name | Type | Required | Description |
|---|
promotion_cas | SecurityActivationPromotionCAS | Yes | — |
|---|
Responses
reconcileSecurityPolicyActivation Responses| Status | Description |
|---|
200 | Reconciled candidate state or identical stored replay. Fields：candidate: SecurityActivationCandidate action: string: / wait / expand / promote / recover / fail / cancel / expire replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/site-publications/security-activations/{candidate_id}/rollback
Clone an old policy into a new monotonic version and stage it
- operationId
rollbackSecurityPolicyActivation- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- 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：security_policies.manage
Parameters
rollbackSecurityPolicyActivation Parameters| Name | In | Type | Required | Description |
|---|
candidate_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
rollbackSecurityPolicyActivation Request body| Name | Type | Required | Description |
|---|
source_policy_version | integer(int64) | Yes | — |
|---|
expected_binding_revision | integer(int64) | Yes | — |
|---|
expected_active_policy_version | integer(int64) | Yes | — |
|---|
target_node_ids | array<string(uuid)> | No | Omitted or empty targets the candidate site's line-group nodes, as SecurityActivationCreateRequest. |
|---|
canary_size | integer | No | — |
|---|
expires_at | string(date-time) | Yes | At most 15 minutes ahead (activation_expiry_too_late). |
|---|
Responses
rollbackSecurityPolicyActivation Responses| Status | Description |
|---|
201 | New monotonic rollback candidate claimed. Fields：candidate: SecurityActivationCandidate replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/site-publications/{publication_id}
Get one publication in the authenticated tenant scope
- operationId
getTenantSitePublication- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- 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：sites.read
Parameters
getTenantSitePublication Parameters| Name | In | Type | Required | Description |
|---|
publication_id | path | string(uuid) | Yes | — |
|---|
Responses
getTenantSitePublication Responses| Status | Description |
|---|
200 | Tenant publication detail with internal metadata redacted. Fields：id: string(uuid) source_revision: integer(int64) config_version_id: string(uuid) rollout_id: string(uuid) target: TenantPublicationTarget node_count: integer created_at: string(date-time) |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list