cdnca

开放接口

/v1/url-auth-policies

7 个接口 · 7 个接口支持 API Key

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
GET/v1/url-auth-policiesList tenant URL authentication policiesAPI Key 可调登录会话
POST/v1/url-auth-policiesCreate a site-bound HMAC-SHA256 URL authentication policyAPI Key 可调登录会话
GET/v1/url-auth-policies/{id}Get URL authentication policy metadataAPI Key 可调登录会话
PATCH/v1/url-auth-policies/{id}Replace URL authentication policy fields using optimistic concurrencyAPI Key 可调登录会话
GET/v1/url-auth-policies/{id}/edge-snapshotGet the deterministic edge-compatible policy snapshotAPI Key 可调登录会话
POST/v1/url-auth-policies/{id}/revokeRevoke the current previous keyAPI Key 可调登录会话
POST/v1/url-auth-policies/{id}/rotateRotate the current HMAC keyAPI Key 可调登录会话

契约文件：api/openapi/v1/control.yaml

接口详情

GET /v1/url-auth-policies

List tenant URL authentication policies

operationId
listURLAuthPolicies
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

说明（契约原文）

Requires url_auth_policies.read. Tenant identities are restricted to their active scope and owner metadata is omitted.

参数

listURLAuthPolicies 参数
名称位置类型必填说明
pagequeryinteger否—
limitqueryinteger否—
statusquerystring: enabled / disabled否—
namequerystring否—
site_idquerystring(uuid)否—

响应

listURLAuthPolicies 响应
状态码说明
200Stable page ordered newest first. Secret material is never returned.

字段：items: array<URLAuthPolicy> total: integer(int64) page: integer limit: integer

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/url-auth-policies

Create a site-bound HMAC-SHA256 URL authentication policy

operationId
createURLAuthPolicy
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

说明（契约原文）

Requires url_auth_policies.manage. The generated key secret is returned exactly once on the first successful request. An identical idempotent replay returns the same policy with replayed=true and no secret. CDNFly Type A, Type B, and MD5 are migration provenance only and cannot be selected for new execution. This endpoint records a deterministic edge-compatible snapshot but does not publish it to Gateway or an edge node.

参数

createURLAuthPolicy 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

createURLAuthPolicy 请求体
名称类型必填说明
site_idstring(uuid)是—
namestring是—
enabledboolean是—
algorithmstring是—
signature_parameterstring是—
expiration_parameterstring是—
key_id_parameterstring是—
bind_client_ipboolean是—
max_clock_skew_secondsinteger是—
max_validity_secondsinteger是—
max_signature_usesinteger是—
excluded_query_parametersarray<string>是—
trusted_proxy_cidrsarray<string>是—
target_scope_idstring(uuid)否—
owner_idstring(uuid)否—

响应

createURLAuthPolicy 响应
状态码说明
201Policy, revision-one snapshot, and first-response-only key secret.

字段：policy: URLAuthPolicy secret?: string replayed: boolean

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
409请求的状态与已有资源或幂等记录冲突。
503A required dependency is unavailable.
500服务内部故障，请求未完成。

失败时怎么办

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

↑ 回到列表

GET /v1/url-auth-policies/{id}

Get URL authentication policy metadata

operationId
getURLAuthPolicy
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

getURLAuthPolicy 参数
名称位置类型必填说明
idpathstring(uuid)是—

响应

getURLAuthPolicy 响应
状态码说明
200Current policy and key metadata without secret, digest, or ciphertext.

字段：site_id: string(uuid) name: string enabled: boolean algorithm: string signature_parameter: string expiration_parameter: string key_id_parameter: string bind_client_ip: boolean max_clock_skew_seconds: integer max_validity_seconds: integer max_signature_uses: integer excluded_query_parameters: array<string> trusted_proxy_cidrs: array<string> id: string(uuid) scope_id: string(uuid) owner?: URLAuthOwner | null site: URLAuthSite migration_marker?: string: cdnfly_type_a_md5 / cdnfly_type_b_md5 current_key: URLAuthKeyMetadata previous_key?: URLAuthKeyMetadata version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

PATCH /v1/url-auth-policies/{id}

Replace URL authentication policy fields using optimistic concurrency

operationId
updateURLAuthPolicy
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

说明（契约原文）

Requires url_auth_policies.manage. The algorithm remains fixed to hmac-sha256 and migration_marker is read-only.

参数

updateURLAuthPolicy 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

updateURLAuthPolicy 请求体
名称类型必填说明
site_idstring(uuid)是—
namestring是—
enabledboolean是—
algorithmstring是—
signature_parameterstring是—
expiration_parameterstring是—
key_id_parameterstring是—
bind_client_ipboolean是—
max_clock_skew_secondsinteger是—
max_validity_secondsinteger是—
max_signature_usesinteger是—
excluded_query_parametersarray<string>是—
trusted_proxy_cidrsarray<string>是—

响应

updateURLAuthPolicy 响应
状态码说明
200Updated policy and immutable snapshot, or a matching replay.

字段：policy: URLAuthPolicy replayed: boolean

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
409请求的状态与已有资源或幂等记录冲突。
500服务内部故障，请求未完成。

失败时怎么办

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

↑ 回到列表

GET /v1/url-auth-policies/{id}/edge-snapshot

Get the deterministic edge-compatible policy snapshot

operationId
getURLAuthPolicyEdgeSnapshot
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

说明（契约原文）

Returns the current cdnca.edge.urlauth/v1 document and its SHA-256. Key paths are deterministic references; no key material is returned. Gateway packaging and delivery are intentionally outside this slice.

参数

getURLAuthPolicyEdgeSnapshot 参数
名称位置类型必填说明
idpathstring(uuid)是—

响应

getURLAuthPolicyEdgeSnapshot 响应
状态码说明
200Current immutable edge snapshot.

字段：policy_id: string(uuid) version: integer(int64) sha256: string document: URLAuthEdgePolicy

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
500服务内部故障，请求未完成。

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/url-auth-policies/{id}/revoke

Revoke the current previous key

operationId
revokeURLAuthPolicyPreviousKey
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

说明（契约原文）

The current signing key cannot be revoked. Disable the policy first when URL authentication must stop.

参数

revokeURLAuthPolicyPreviousKey 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

revokeURLAuthPolicyPreviousKey 请求体
名称类型必填说明
key_idstring是—

响应

revokeURLAuthPolicyPreviousKey 响应
状态码说明
200Previous key revoked and policy version incremented.

字段：policy: URLAuthPolicy replayed: boolean

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
409请求的状态与已有资源或幂等记录冲突。
500服务内部故障，请求未完成。

失败时怎么办

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

↑ 回到列表

POST /v1/url-auth-policies/{id}/rotate

Rotate the current HMAC key

operationId
rotateURLAuthPolicyKey
认证
  • API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

说明（契约原文）

Promotes the current key to previous, revokes an older previous key, and returns the new secret exactly once. Matching idempotent replay returns no secret.

参数

rotateURLAuthPolicyKey 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

响应

rotateURLAuthPolicyKey 响应
状态码说明
200Rotated policy and first-response-only key secret.

字段：policy: URLAuthPolicy secret?: string replayed: boolean

400请求体或参数不合法。
401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
404请求的资源不存在。
409请求的状态与已有资源或幂等记录冲突。
503A required dependency is unavailable.
500服务内部故障，请求未完成。

失败时怎么办

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

↑ 回到列表