/v1/tenant-scopes

POST /v1/tenant-scopes/{scope_id}/l4-line-switches

Create an idempotent line-group switch

operationId

createL4LineSwitch

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

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Request body

application/json · Required：Yes

Responses

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/tenant-scopes/{scope_id}/l4-line-switches/current

Read the latest durable switch for operator recovery

operationId

getCurrentL4LineSwitch

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

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Responses

What to do on failure

• 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

GET /v1/tenant-scopes/{scope_id}/l4-line-switches/{switch_id}

Read durable switch state

operationId

getL4LineSwitch

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

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Responses

What to do on failure

• 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/tenant-scopes/{scope_id}/l4-line-switches/{switch_id}/reconcile

Advance one idempotent state-machine step from durable facts

operationId

reconcileL4LineSwitch

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

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

The request has no body and cannot nominate a desired state. Production workers call the same service method.

Parameters

Responses

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/tenant-scopes/{scope_id}/sites/{site_id}/telemetry-capture-policy

operationId

getSiteCapturePolicy

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：site_capture.read

Description (from the contract)

A readable site that never saved a policy answers 200 with state=unconfigured, revision 0 and the default (capture off) document; create it with expected_revision 0. 404 means the site is missing, deleted or not visible to the caller.

Parameters

Responses

What to do on failure

• 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

PUT /v1/tenant-scopes/{scope_id}/sites/{site_id}/telemetry-capture-policy

operationId

updateSiteCapturePolicy

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：site_capture.manage

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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/tenant-scopes/{tenant_scope_id}/challenge-policies

List active challenge policies in one tenant scope

operationId

listChallengePolicies

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：challenge_policies.read

Description (from the contract)

Requires challenge_policies.read. Results use stable keyset ordering; the versioned HMAC-SHA256 cursor is opaque and must be replayed unchanged with the same authenticated actor, target scope, filters, limit, and sort. Invalid cursors return 400 before storage is read. Pages may contain fewer than the requested limit to stay within the default 256 KiB response byte budget; next_cursor resumes after the last emitted item. Soft-deleted policies are excluded. A tenant principal targeting another tenant receives the same 404 shape as an unknown scope.

Parameters

Responses

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/tenant-scopes/{tenant_scope_id}/challenge-policies

Create a challenge policy for a tenant-owned site and host

operationId

createChallengePolicy

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：challenge_policies.manage

Description (from the contract)

Requires challenge_policies.manage and a currently valid, non-grace sites.manage entitlement. The site must belong to the target tenant and the host must equal the site domain or be covered by its wildcard. The request creates immutable revision 1 and a transactional audit event. A completed same-actor, same-scope, same-operation, same-key/same-payload retry returns the frozen stored result before mutable site or entitlement state is rechecked; a new request still performs all current checks. A key reused with another payload returns 409.

Parameters

Request body

application/json · Required：Yes

Responses

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/tenant-scopes/{tenant_scope_id}/challenge-policies/{policy_id}

Read one challenge policy

operationId

getChallengePolicy

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：challenge_policies.read

Description (from the contract)

Requires challenge_policies.read. Soft-deleted, unknown, and out-of-tenant policy IDs all return the same 404 response.

Parameters

Responses

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

PATCH /v1/tenant-scopes/{tenant_scope_id}/challenge-policies/{policy_id}

Append a new challenge policy configuration revision

operationId

updateChallengePolicy

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：challenge_policies.manage

Description (from the contract)

Requires challenge_policies.manage and a currently valid, non-grace sites.manage entitlement. If-Match is compared with the current revision under a row lock. Site and host identity cannot be changed.

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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

DELETE /v1/tenant-scopes/{tenant_scope_id}/challenge-policies/{policy_id}

Soft-delete a challenge policy by appending a tombstone revision

operationId

deleteChallengePolicy

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：challenge_policies.manage

Description (from the contract)

Requires challenge_policies.manage. The request body must be empty. Historical revisions remain immutable so future publication references cannot be destroyed. Delete is intentionally allowed during entitlement grace because it reduces active configuration.

Parameters

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/challenge-policies/{policy_id}/disable

Disable a challenge policy with revision CAS

operationId

disableChallengePolicy

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：challenge_policies.manage

Description (from the contract)

Requires challenge_policies.manage. The body must be absent or exactly an empty JSON object. Disabling is allowed during entitlement grace because it reduces active configuration. Disabling an already disabled policy returns 409.

Parameters

Request body

application/json · Required：No

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/challenge-policies/{policy_id}/enable

Enable a challenge policy with revision CAS

operationId

enableChallengePolicy

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：challenge_policies.manage

Description (from the contract)

Requires challenge_policies.manage and a currently valid, non-grace sites.manage entitlement. The body must be absent or exactly an empty JSON object. Enabling an already enabled policy returns 409.

Parameters

Request body

application/json · Required：No

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/challenge-policies/{policy_id}/publications

Publish one exact enabled challenge policy revision to Edge nodes

operationId

publishChallengePolicy

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：challenge_policies.manage

Description (from the contract)

Requires challenge_policies.manage. The current policy revision is re-authorized and locked before resolving its opaque key reference. The immutable artifact is signed and HPKE-encrypted separately for each eligible node. Missing key material or an unconfigured external adapter fails closed and does not change the active Edge configuration.

Parameters

Request body

application/json · Required：No

Responses

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.
• 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/tenant-scopes/{tenant_scope_id}/challenge-policies/{policy_id}/publications/{rollout_id}

Read the bounded rollout state for an exact policy artifact

operationId

getChallengePolicyPublication

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：challenge_policies.read

Description (from the contract)

Requires challenge_policies.read. The rollout must belong to the target tenant, policy, and revision; another same-tenant rollout is not relabeled through this path. This read has no publication or promotion side effects.

Parameters

Responses

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/tenant-scopes/{tenant_scope_id}/challenge-policies/{policy_id}/publications/{rollout_id}/promote

Promote an exact healthy challenge rollout into Edge configuration

operationId

promoteChallengePolicyPublication

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：challenge_policies.manage

Description (from the contract)

Requires challenge_policies.manage. Promotion is revision-CAS and idempotent. Only a fully healthy rollout whose immutable artifact binds the same tenant, policy, and revision can advance the signed Edge configuration. Partial, failed, stale, forged, or cross-policy rollouts preserve the current configuration and LKG.

Parameters

Request body

application/json · Required：No

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/error-page-publications

发布租户作用域的错误页配置

operationId

publishErrorPageConfiguration

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：edge_publications.manage

Description (from the contract)

Requires a platform session with edge_publications.manage. If-Match is the exact current source revision. Target nodes or an immutable line-group snapshot, health policy, deadline, actor, and idempotency metadata are committed through the existing production publisher. An outcome_unknown response may be retried only with the unchanged body, If-Match, path, and Idempotency-Key.

Parameters

Request body

application/json · Required：Yes

Responses

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/tenant-scopes/{tenant_scope_id}/error-page-publications/{publication_id}

读取一个不可变错误页发布结果

operationId

getErrorPagePublication

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：edge_publications.read

Description (from the contract)

Requires edge_publications.read. The session and RBAC grant are checked again in the read transaction. The selected publication must belong to tenant_scope_id and its ordinal-one configuration artifact must use the signed error-page snapshot media type. Cross-scope resources are never returned.

Parameters

Responses

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

GET /v1/tenant-scopes/{tenant_scope_id}/http-policies

List non-deleted HTTP policies in one tenant scope

operationId

listHTTPPolicies

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：http_policies.read

Description (from the contract)

Requires http_policies.read. Results use stable keyset ordering. The server may emit fewer items than limit so the complete ListResult JSON envelope, including next_cursor and the trailing response newline, stays within the 2 MiB byte budget. A single maximum schema-legal policy is always returned. When more rows remain, the opaque next_cursor is anchored to the last item emitted. Pagination resumes strictly after it without gaps or duplicates. Tenant principals see only sites they own. Platform principals must provide this explicit tenant scope and pass the live database permission check.

Parameters

Responses

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/tenant-scopes/{tenant_scope_id}/http-policies

Create revision one for a tenant-owned site

operationId

createHTTPPolicy

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：http_policies.manage

Description (from the contract)

Requires http_policies.manage and a currently valid, non-grace sites.manage entitlement. Same-key same-payload retries return the stored result; a key reused with another payload returns 409. JSON is limited to 1 MiB and duplicate keys, unknown fields, and trailing values are rejected. A platform principal whose role holds http_policies.manage (or platform.admin) writes any site of this tenant scope, as do the update, enable, disable, and delete operations; the revision records the platform actor and the audit event's scope is this tenant scope.

Parameters

Request body

application/json · Required：Yes

Responses

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/tenant-scopes/{tenant_scope_id}/http-policies/publication-preview

Read a deterministic unsigned Edge v1 source snapshot

operationId

previewHTTPPolicyPublication

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：http_policies.read

Description (from the contract)

Requires http_policies.read. The result contains only enabled, non-deleted policies visible in the target tenant and is sorted by site_id. state is always preview. The SHA-256 covers canonical snapshot JSON with a trailing newline. It is not a signature or delivery receipt.

Parameters

Responses

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/tenant-scopes/{tenant_scope_id}/http-policies/{policy_id}

Read one HTTP policy

operationId

getHTTPPolicy

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：http_policies.read

Description (from the contract)

Requires http_policies.read. Unknown, deleted, out-of-tenant, and tenant actor non-owned policy IDs share the same 404 response.

Parameters

Responses

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

PATCH /v1/tenant-scopes/{tenant_scope_id}/http-policies/{policy_id}

Append a configuration revision

operationId

updateHTTPPolicy

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：http_policies.manage

Description (from the contract)

Requires http_policies.manage and a currently valid, non-grace sites.manage entitlement. If-Match is compared under a row lock. Site identity and enabled state cannot be changed by this operation.

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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

DELETE /v1/tenant-scopes/{tenant_scope_id}/http-policies/{policy_id}

Soft-delete a policy by appending a tombstone revision

operationId

deleteHTTPPolicy

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：http_policies.manage

Description (from the contract)

Requires http_policies.manage, Idempotency-Key, and revision CAS. The body must be empty. Delete remains available during entitlement grace and preserves all historical revisions.

Parameters

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/http-policies/{policy_id}/disable

Disable a policy with revision CAS

operationId

disableHTTPPolicy

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：http_policies.manage

Description (from the contract)

Requires http_policies.manage. The body must be exactly an empty JSON object. Disable remains available during entitlement grace.

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/http-policies/{policy_id}/enable

Enable a policy with revision CAS

operationId

enableHTTPPolicy

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：http_policies.manage

Description (from the contract)

Requires http_policies.manage and a currently valid, non-grace sites.manage entitlement. The body must be exactly an empty JSON object.

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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/tenant-scopes/{tenant_scope_id}/origin-auth/credentials

List redacted credential heads in one tenant

operationId

listOriginAuthCredentials

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：origin_auth.read

Parameters

Responses

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/tenant-scopes/{tenant_scope_id}/origin-auth/credentials

Encrypt and append credential revision 1

operationId

createOriginAuthCredential

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：origin_auth.manage

Description (from the contract)

Requires origin_auth.manage and a valid sites.manage entitlement. The credential remains pending until an injected real verifier accepts it. Same-key same-payload retries replay the stored redacted response.

Parameters

Request body

application/json · Required：Yes

Responses

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/tenant-scopes/{tenant_scope_id}/origin-auth/credentials/{credential_id}

Read one redacted credential head

operationId

getOriginAuthCredential

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：origin_auth.read

Parameters

Responses

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

DELETE /v1/tenant-scopes/{tenant_scope_id}/origin-auth/credentials/{credential_id}

Append a credential tombstone revision

operationId

deleteOriginAuthCredential

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：origin_auth.manage

Description (from the contract)

The body must be exactly an empty JSON object. A credential referenced by a currently enabled rule cannot be deleted. Historical publication rows and prior encrypted revisions are not mutated.

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/origin-auth/credentials/{credential_id}/disable

Append a disabled credential revision

operationId

disableOriginAuthCredential

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：origin_auth.manage

Description (from the contract)

The body must be exactly an empty JSON object. A credential referenced by an enabled rule must first be removed from or disabled in that rule.

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/origin-auth/credentials/{credential_id}/replace

Encrypt replacement material with the active envelope key

operationId

replaceOriginAuthCredential

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：origin_auth.manage

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/origin-auth/credentials/{credential_id}/verify

Invoke the injected verifier and append a verified revision

operationId

verifyOriginAuthCredential

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：origin_auth.manage

Description (from the contract)

The body must be exactly an empty JSON object. If no real verifier is configured, the response is 503 and the credential remains pending. This endpoint never treats schema validation or a synthetic network probe as successful provider verification.

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/origin-auth/edge-publications

发布租户作用域的源站鉴权配置

operationId

publishOriginAuthEdgeConfiguration

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：edge_publications.manage origin_auth.manage

Description (from the contract)

Requires a platform session with edge_publications.manage and origin_auth.manage. If-Match is the exact latest source revision. The server locks each target node and its active recipient key, produces one signed HPKE artifact per node, and commits the immutable config, rollout, deployment commands, and outbox records in one transaction. An outcome_unknown response may be retried only with the unchanged body, path, If-Match, Idempotency-Key, X-Request-ID, X-Correlation-ID, Traceparent, and X-Task-ID.

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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/tenant-scopes/{tenant_scope_id}/origin-auth/edge-publications/{publication_id}

读取一个不可变源站鉴权发布结果

operationId

getOriginAuthEdgePublication

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：edge_publications.read origin_auth.read

Description (from the contract)

Requires edge_publications.read and origin_auth.read. The session and both grants are checked again in the read transaction. The result is reconstructed only from the immutable rollout, config, source snapshot, per-node artifact, recipient-key, and deployment-command facts. Cross-scope or other secret-rollout subtypes are rejected.

Parameters

Responses

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

GET /v1/tenant-scopes/{tenant_scope_id}/origin-auth/publications

Read the latest deterministic secret-free snapshot

operationId

getLatestOriginAuthPublication

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：origin_auth.read

Parameters

Responses

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/tenant-scopes/{tenant_scope_id}/origin-auth/publications

Append the next tenant publication snapshot

operationId

createOriginAuthPublication

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：origin_auth.manage

Description (from the contract)

If-Match is the current publication revision and may be "0" for the first snapshot. The body must be exactly an empty JSON object. The snapshot contains Edge-aligned public rule fields and opaque credential revision references only. It is not an Edge secret file or deployment.

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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/tenant-scopes/{tenant_scope_id}/origin-auth/rules

List current rule revisions

operationId

listOriginAuthRules

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：origin_auth.read

Parameters

Responses

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/tenant-scopes/{tenant_scope_id}/origin-auth/rules

Create a tenant, site, and source-bound rule

operationId

createOriginAuthRule

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：origin_auth.manage

Description (from the contract)

The source must be an HTTPS port 443 source in the same tenant and its host must exactly equal the normalized endpoint host. An enabled rule can reference only a verified credential revision with matching provider and sufficient validity.

Parameters

Request body

application/json · Required：Yes

Responses

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/tenant-scopes/{tenant_scope_id}/origin-auth/rules/{rule_id}

Read one current rule revision

operationId

getOriginAuthRule

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：origin_auth.read

Parameters

Responses

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

PATCH /v1/tenant-scopes/{tenant_scope_id}/origin-auth/rules/{rule_id}

Append a rule configuration revision

operationId

updateOriginAuthRule

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：origin_auth.manage

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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

DELETE /v1/tenant-scopes/{tenant_scope_id}/origin-auth/rules/{rule_id}

Append a rule tombstone revision

operationId

deleteOriginAuthRule

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：origin_auth.manage

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/origin-auth/rules/{rule_id}/disable

Disable a rule by revision CAS

operationId

disableOriginAuthRule

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：origin_auth.manage

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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

POST /v1/tenant-scopes/{tenant_scope_id}/origin-auth/rules/{rule_id}/enable

Enable a rule after verified credential gates pass

operationId

enableOriginAuthRule

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：origin_auth.manage

Parameters

Request body

application/json · Required：Yes

Responses

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.
• 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.