Operation details
GET /v1/url-auth-policies
List tenant URL authentication policies
- operationId
listURLAuthPolicies- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires url_auth_policies.read. Tenant identities are restricted to their active scope and owner metadata is omitted.
Parameters
listURLAuthPolicies Parameters| Name | In | Type | Required | Description |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
status | query | string: enabled / disabled | No | — |
|---|
name | query | string | No | — |
|---|
site_id | query | string(uuid) | No | — |
|---|
Responses
listURLAuthPolicies Responses| Status | Description |
|---|
200 | Stable page ordered newest first. Secret material is never returned. Fields：items: array<URLAuthPolicy> total: integer(int64) page: integer limit: integer |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/url-auth-policies
Create a site-bound HMAC-SHA256 URL authentication policy
- operationId
createURLAuthPolicy- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
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.
Parameters
createURLAuthPolicy Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createURLAuthPolicy Request body| Name | Type | Required | Description |
|---|
site_id | string(uuid) | Yes | — |
|---|
name | string | Yes | — |
|---|
enabled | boolean | Yes | — |
|---|
algorithm | string | Yes | — |
|---|
signature_parameter | string | Yes | — |
|---|
expiration_parameter | string | Yes | — |
|---|
key_id_parameter | string | Yes | — |
|---|
bind_client_ip | boolean | Yes | — |
|---|
max_clock_skew_seconds | integer | Yes | — |
|---|
max_validity_seconds | integer | Yes | — |
|---|
max_signature_uses | integer | Yes | — |
|---|
excluded_query_parameters | array<string> | Yes | — |
|---|
trusted_proxy_cidrs | array<string> | Yes | — |
|---|
target_scope_id | string(uuid) | No | — |
|---|
owner_id | string(uuid) | No | — |
|---|
Responses
createURLAuthPolicy Responses| Status | Description |
|---|
201 | Policy, revision-one snapshot, and first-response-only key secret. Fields：policy: URLAuthPolicy secret?: string replayed: boolean |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
503 | A required dependency is unavailable. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.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.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
GET /v1/url-auth-policies/{id}
Get URL authentication policy metadata
- operationId
getURLAuthPolicy- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
getURLAuthPolicy Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
getURLAuthPolicy Responses| Status | Description |
|---|
200 | Current policy and key metadata without secret, digest, or ciphertext. Fields：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 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
PATCH /v1/url-auth-policies/{id}
Replace URL authentication policy fields using optimistic concurrency
- operationId
updateURLAuthPolicy- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires url_auth_policies.manage. The algorithm remains fixed to hmac-sha256 and migration_marker is read-only.
Parameters
updateURLAuthPolicy Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
updateURLAuthPolicy Request body| Name | Type | Required | Description |
|---|
site_id | string(uuid) | Yes | — |
|---|
name | string | Yes | — |
|---|
enabled | boolean | Yes | — |
|---|
algorithm | string | Yes | — |
|---|
signature_parameter | string | Yes | — |
|---|
expiration_parameter | string | Yes | — |
|---|
key_id_parameter | string | Yes | — |
|---|
bind_client_ip | boolean | Yes | — |
|---|
max_clock_skew_seconds | integer | Yes | — |
|---|
max_validity_seconds | integer | Yes | — |
|---|
max_signature_uses | integer | Yes | — |
|---|
excluded_query_parameters | array<string> | Yes | — |
|---|
trusted_proxy_cidrs | array<string> | Yes | — |
|---|
Responses
updateURLAuthPolicy Responses| Status | Description |
|---|
200 | Updated policy and immutable snapshot, or a matching replay. Fields：policy: URLAuthPolicy replayed: boolean |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
GET /v1/url-auth-policies/{id}/edge-snapshot
Get the deterministic edge-compatible policy snapshot
- operationId
getURLAuthPolicyEdgeSnapshot- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
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.
Parameters
getURLAuthPolicyEdgeSnapshot Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
getURLAuthPolicyEdgeSnapshot Responses| Status | Description |
|---|
200 | Current immutable edge snapshot. Fields：policy_id: string(uuid) version: integer(int64) sha256: string document: URLAuthEdgePolicy |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/url-auth-policies/{id}/revoke
Revoke the current previous key
- operationId
revokeURLAuthPolicyPreviousKey- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
The current signing key cannot be revoked. Disable the policy first when URL authentication must stop.
Parameters
revokeURLAuthPolicyPreviousKey Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
revokeURLAuthPolicyPreviousKey Request body| Name | Type | Required | Description |
|---|
key_id | string | Yes | — |
|---|
Responses
revokeURLAuthPolicyPreviousKey Responses| Status | Description |
|---|
200 | Previous key revoked and policy version incremented. Fields：policy: URLAuthPolicy replayed: boolean |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/url-auth-policies/{id}/rotate
Rotate the current HMAC key
- operationId
rotateURLAuthPolicyKey- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Promotes the current key to previous, revokes an older previous key, and returns the new secret exactly once. Matching idempotent replay returns no secret.
Parameters
rotateURLAuthPolicyKey Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Responses
rotateURLAuthPolicyKey Responses| Status | Description |
|---|
200 | Rotated policy and first-response-only key secret. Fields：policy: URLAuthPolicy secret?: string replayed: boolean |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
503 | A required dependency is unavailable. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list