/v1/tenant-scopes

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

Create an idempotent line-group switch

operationId

createL4LineSwitch

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Read the latest durable switch for operator recovery

operationId

getCurrentL4LineSwitch

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

响应

失败时怎么办

• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Read durable switch state

operationId

getL4LineSwitch

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

响应

失败时怎么办

• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Advance one idempotent state-machine step from durable facts

operationId

reconcileL4LineSwitch

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

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

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

operationId

getSiteCapturePolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：site_capture.read

说明（契约原文）

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.

参数

响应

失败时怎么办

• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

operationId

updateSiteCapturePolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：site_capture.manage

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

List active challenge policies in one tenant scope

operationId

listChallengePolicies

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：challenge_policies.read

说明（契约原文）

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.

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

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

operationId

createChallengePolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：challenge_policies.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Read one challenge policy

operationId

getChallengePolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：challenge_policies.read

说明（契约原文）

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

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Append a new challenge policy configuration revision

operationId

updateChallengePolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：challenge_policies.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Soft-delete a challenge policy by appending a tombstone revision

operationId

deleteChallengePolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：challenge_policies.manage

说明（契约原文）

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.

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Disable a challenge policy with revision CAS

operationId

disableChallengePolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：challenge_policies.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：否

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Enable a challenge policy with revision CAS

operationId

enableChallengePolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：challenge_policies.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：否

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Publish one exact enabled challenge policy revision to Edge nodes

operationId

publishChallengePolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：challenge_policies.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：否

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：challenge_policies.read

说明（契约原文）

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.

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：challenge_policies.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：否

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

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

operationId

publishErrorPageConfiguration

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：edge_publications.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/tenant-scopes/{tenant_scope_id}/error-page-publications/{publication_id}

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

operationId

getErrorPagePublication

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：edge_publications.read

说明（契约原文）

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.

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

List non-deleted HTTP policies in one tenant scope

operationId

listHTTPPolicies

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：http_policies.read

说明（契约原文）

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.

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Create revision one for a tenant-owned site

operationId

createHTTPPolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：http_policies.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Read a deterministic unsigned Edge v1 source snapshot

operationId

previewHTTPPolicyPublication

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：http_policies.read

说明（契约原文）

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.

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Read one HTTP policy

operationId

getHTTPPolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：http_policies.read

说明（契约原文）

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

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Append a configuration revision

operationId

updateHTTPPolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：http_policies.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Soft-delete a policy by appending a tombstone revision

operationId

deleteHTTPPolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：http_policies.manage

说明（契约原文）

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.

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Disable a policy with revision CAS

operationId

disableHTTPPolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：http_policies.manage

说明（契约原文）

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

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Enable a policy with revision CAS

operationId

enableHTTPPolicy

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：http_policies.manage

说明（契约原文）

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

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

List redacted credential heads in one tenant

operationId

listOriginAuthCredentials

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.read

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Encrypt and append credential revision 1

operationId

createOriginAuthCredential

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Read one redacted credential head

operationId

getOriginAuthCredential

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.read

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Append a credential tombstone revision

operationId

deleteOriginAuthCredential

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Append a disabled credential revision

operationId

disableOriginAuthCredential

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Encrypt replacement material with the active envelope key

operationId

replaceOriginAuthCredential

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Invoke the injected verifier and append a verified revision

operationId

verifyOriginAuthCredential

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

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

operationId

publishOriginAuthEdgeConfiguration

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：edge_publications.manage origin_auth.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

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

operationId

getOriginAuthEdgePublication

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：edge_publications.read origin_auth.read

说明（契约原文）

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.

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Read the latest deterministic secret-free snapshot

operationId

getLatestOriginAuthPublication

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.read

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Append the next tenant publication snapshot

operationId

createOriginAuthPublication

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

List current rule revisions

operationId

listOriginAuthRules

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.read

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Create a tenant, site, and source-bound rule

operationId

createOriginAuthRule

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

说明（契约原文）

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.

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Read one current rule revision

operationId

getOriginAuthRule

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.read

参数

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Append a rule configuration revision

operationId

updateOriginAuthRule

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Append a rule tombstone revision

operationId

deleteOriginAuthRule

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Disable a rule by revision CAS

operationId

disableOriginAuthRule

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

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

Enable a rule after verified credential gates pass

operationId

enableOriginAuthRule

认证

• 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：origin_auth.manage

参数

请求体

application/json · 必填：是

响应

失败时怎么办

• 400 按字段说明修正参数或请求体再发；不要原样重试。
• 401 检查凭据格式、是否过期或被轮换。
• 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
• 404 资源不存在或不属于当前租户。
• 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
• 412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
• 503 依赖暂不可用：稍后用原 Idempotency-Key 重试。