Operation details
GET /v1/security-policies
List tenant WAF, CC and ACL policies
- operationId
listSecurityPolicies- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.read
Description (from the contract)
Requires security_policies.read. Tenant identities see only their active scope and never receive owner metadata; platform identities may filter across tenant owners.
Parameters
listSecurityPolicies Parameters| Name | In | Type | Required | Description |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
kind | query | string: waf / cc / acl | No | Policy kind; omit for all kinds. |
|---|
status | query | string: enabled / disabled | No | — |
|---|
name | query | string | No | — |
|---|
id | query | string(uuid) | No | Exact canonical security policy UUID filter. |
|---|
owner | query | string | No | Platform-only owner name, username, or exact UUID filter. |
|---|
scope | query | string: global / site / system | No | WAF rule libraries only: requires kind=waf (400 otherwise). system: subscribed platform rule library copies; site: own libraries bound to a site; global: own libraries no site is bound to. Total and counts follow the filter. |
|---|
Responses
listSecurityPolicies Responses| Status | Description |
|---|
200 | Stable page ordered newest first. Fields：items: array<SecurityPolicy> 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/security-policies
Create a versioned WAF, CC or ACL policy
- operationId
createSecurityPolicy- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Description (from the contract)
Requires security_policies.manage. Platform identities must provide an active tenant target_scope_id and owner_id; tenant identities are fixed to their current scope and identity. Rule IDs are server-generated and identical idempotent replay returns the original IDs. This control-plane slice does not claim edge publication or enforcement.
Parameters
createSecurityPolicy Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createSecurityPolicy Request body| Name | Type | Required | Description |
|---|
kind | string: waf / cc / acl | Yes | waf = WAF rule library, cc = CC protection, acl = access control. |
|---|
name | string | Yes | — |
|---|
description | string | Yes | — |
|---|
enabled | boolean | Yes | — |
|---|
default_action | string: allow / block | Yes | — |
|---|
rules | array<SecurityPolicyRuleInput> | Yes | — |
|---|
cc_settings | SecurityPolicyCCSettings | No | CC only. Site-level ban/pass durations (override every rule's) and the auto switch (自动切换). Omitted keeps the rules' own values. |
|---|
waf_settings | SecurityPolicyWAFSettings | No | WAF only (node CAPABILITY_NAME_WAF v2). Omitted (or defend mode without auto_block) is stored as absent. |
|---|
target_scope_id | string(uuid) | No | — |
|---|
owner_id | string(uuid) | No | — |
|---|
Responses
createSecurityPolicy Responses| Status | Description |
|---|
201 | Policy and immutable revision-one snapshot created, or an identical request replayed. Fields：kind: string: waf / cc / acl name: string description: string enabled: boolean default_action: string: allow / block rules: array<SecurityPolicyRuleInput> cc_settings?: SecurityPolicyCCSettings waf_settings?: SecurityPolicyWAFSettings id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null 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. |
|---|
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.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/security-policies/batch
Enable, disable or delete selected WAF rule libraries item by item
- operationId
batchSecurityPolicies- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Description (from the contract)
Requires security_policies.manage. Each item is written on its own with a version check (CAS) under an item key derived from Idempotency-Key, so retrying the same batch replays written items. Results come back in request order, one per item; refusals (version conflict, system library, not found, in use, ...) are item results and do not stop the batch. A store failure marks that item error and the rest not_attempted. System (platform) libraries are never modified.
Parameters
batchSecurityPolicies Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
batchSecurityPolicies Request body| Name | Type | Required | Description |
|---|
action | string: enable / disable / delete | Yes | — |
|---|
items | array<object> | Yes | — |
|---|
Responses
batchSecurityPolicies Responses| Status | Description |
|---|
200 | One result per item, in request order. Fields：items: array<object> |
|---|
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
GET /v1/security-policies/filters
List persisted CC filters
- operationId
listSecurityPolicyFilters- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.read
Description (from the contract)
Requires security_policies.read. Rows created before the filter resource was introduced are materialized from real CC rule actions; newly created rows are independent versioned resources. Tenant identities see only their active scope and never receive owner metadata.
Parameters
listSecurityPolicyFilters Parameters| Name | In | Type | Required | Description |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
status | query | string: enabled / disabled | No | — |
|---|
type | query | string | No | — |
|---|
name | query | string | No | — |
|---|
id | query | string(uuid) | No | — |
|---|
owner | query | string | No | Platform-only owner filter. |
|---|
Responses
listSecurityPolicyFilters Responses| Status | Description |
|---|
200 | Filter rows projected deterministically from real CC rule actions. Fields：items: array<SecurityPolicyReference> total: integer 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/security-policies/filters
Create a versioned CC filter
- operationId
createSecurityPolicyFilter- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Description (from the contract)
Requires security_policies.manage. Platform identities must provide target_scope_id and owner_id; tenant identities are fixed to their current scope.
Parameters
createSecurityPolicyFilter Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createSecurityPolicyFilter Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
description | string | Yes | — |
|---|
enabled | boolean | Yes | — |
|---|
type | string | Yes | — |
|---|
parameters | object | Yes | — |
|---|
target_scope_id | string(uuid) | No | — |
|---|
owner_id | string(uuid) | No | — |
|---|
Responses
createSecurityPolicyFilter Responses| Status | Description |
|---|
201 | — Fields：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
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. |
|---|
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.
↑ Back to list
GET /v1/security-policies/filters/{id}
Get one CC filter
- operationId
getSecurityPolicyFilter- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.read
Parameters
getSecurityPolicyFilter Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
getSecurityPolicyFilter Responses| Status | Description |
|---|
200 | — Fields：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
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. |
|---|
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.
↑ Back to list
PATCH /v1/security-policies/filters/{id}
Replace a CC filter using optimistic concurrency
- operationId
updateSecurityPolicyFilter- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Parameters
updateSecurityPolicyFilter 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
updateSecurityPolicyFilter Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
description | string | Yes | — |
|---|
enabled | boolean | Yes | — |
|---|
type | string | Yes | — |
|---|
parameters | object | Yes | — |
|---|
Responses
updateSecurityPolicyFilter Responses| Status | Description |
|---|
200 | — Fields：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
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. |
|---|
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.
↑ Back to list
DELETE /v1/security-policies/filters/{id}
Soft-delete a CC filter
- operationId
deleteSecurityPolicyFilter- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Parameters
deleteSecurityPolicyFilter Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Responses
deleteSecurityPolicyFilter Responses| Status | Description |
|---|
204 | Filter deleted |
|---|
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. |
|---|
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.
↑ Back to list
POST /v1/security-policies/filters/{id}/disable
Disable a CC filter
- operationId
disableSecurityPolicyFilter- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Parameters
disableSecurityPolicyFilter Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Responses
disableSecurityPolicyFilter Responses| Status | Description |
|---|
200 | Filter disabled. Fields：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
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. |
|---|
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.
↑ Back to list
POST /v1/security-policies/filters/{id}/enable
Enable a CC filter
- operationId
enableSecurityPolicyFilter- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Parameters
enableSecurityPolicyFilter Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Responses
enableSecurityPolicyFilter Responses| Status | Description |
|---|
200 | Filter enabled. Fields：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
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. |
|---|
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.
↑ Back to list
GET /v1/security-policies/matchers
List persisted CC matchers
- operationId
listSecurityPolicyMatchers- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.read
Description (from the contract)
Requires security_policies.read. Rows created before the matcher resource was introduced are materialized from the existing CC rules; newly created rows are independent versioned resources. Tenant identities see only their active scope and never receive owner metadata.
Parameters
listSecurityPolicyMatchers Parameters| Name | In | Type | Required | Description |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
status | query | string: enabled / disabled | No | — |
|---|
name | query | string | No | — |
|---|
id | query | string(uuid) | No | — |
|---|
owner | query | string | No | Platform-only owner filter. |
|---|
Responses
listSecurityPolicyMatchers Responses| Status | Description |
|---|
200 | Matcher rows projected deterministically from real CC policy conditions. Fields：items: array<SecurityPolicyReference> total: integer 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/security-policies/matchers
Create a versioned CC matcher
- operationId
createSecurityPolicyMatcher- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Description (from the contract)
Requires security_policies.manage. Platform identities must provide target_scope_id and owner_id; tenant identities are fixed to their current scope.
Parameters
createSecurityPolicyMatcher Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createSecurityPolicyMatcher Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
description | string | Yes | — |
|---|
enabled | boolean | Yes | — |
|---|
field | string | Yes | — |
|---|
operator | string | Yes | — |
|---|
key | string | No | — |
|---|
values | array<string> | Yes | — |
|---|
target_scope_id | string(uuid) | No | — |
|---|
owner_id | string(uuid) | No | — |
|---|
Responses
createSecurityPolicyMatcher Responses| Status | Description |
|---|
201 | Matcher created with revision one, or an identical request replayed. Fields：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
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. |
|---|
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.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/security-policies/matchers/{id}
Get one CC matcher
- operationId
getSecurityPolicyMatcher- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.read
Parameters
getSecurityPolicyMatcher Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
getSecurityPolicyMatcher Responses| Status | Description |
|---|
200 | — Fields：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
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. |
|---|
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.
↑ Back to list
PATCH /v1/security-policies/matchers/{id}
Replace a CC matcher using optimistic concurrency
- operationId
updateSecurityPolicyMatcher- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Parameters
updateSecurityPolicyMatcher 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
updateSecurityPolicyMatcher Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
description | string | Yes | — |
|---|
enabled | boolean | Yes | — |
|---|
field | string | Yes | — |
|---|
operator | string | Yes | — |
|---|
key | string | No | — |
|---|
values | array<string> | Yes | — |
|---|
Responses
updateSecurityPolicyMatcher Responses| Status | Description |
|---|
200 | — Fields：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
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. |
|---|
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.
↑ Back to list
DELETE /v1/security-policies/matchers/{id}
Soft-delete a CC matcher
- operationId
deleteSecurityPolicyMatcher- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Parameters
deleteSecurityPolicyMatcher Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Responses
deleteSecurityPolicyMatcher Responses| Status | Description |
|---|
204 | Matcher deleted |
|---|
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. |
|---|
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.
↑ Back to list
POST /v1/security-policies/matchers/{id}/disable
Disable a CC matcher
- operationId
disableSecurityPolicyMatcher- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Parameters
disableSecurityPolicyMatcher Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Responses
disableSecurityPolicyMatcher Responses| Status | Description |
|---|
200 | Matcher disabled. Fields：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
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. |
|---|
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.
↑ Back to list
POST /v1/security-policies/matchers/{id}/enable
Enable a CC matcher
- operationId
enableSecurityPolicyMatcher- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Parameters
enableSecurityPolicyMatcher Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Responses
enableSecurityPolicyMatcher Responses| Status | Description |
|---|
200 | Matcher enabled. Fields：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
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. |
|---|
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.
↑ Back to list
GET /v1/security-policies/{id}
Get one active WAF, CC or ACL policy
- operationId
getSecurityPolicy- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.read
Parameters
getSecurityPolicy Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
getSecurityPolicy Responses| Status | Description |
|---|
200 | Current policy projection. Owner is omitted for tenant identities. Fields：kind: string: waf / cc / acl name: string description: string enabled: boolean default_action: string: allow / block rules: array<SecurityPolicyRuleInput> cc_settings?: SecurityPolicyCCSettings waf_settings?: SecurityPolicyWAFSettings id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null 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/security-policies/{id}
Replace policy fields using optimistic concurrency
- operationId
updateSecurityPolicy- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Description (from the contract)
Requires security_policies.manage. Existing rule IDs must belong to this policy; omitted IDs create new rules. A successful update appends one immutable revision snapshot.
Parameters
updateSecurityPolicy 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
updateSecurityPolicy Request body| Name | Type | Required | Description |
|---|
kind | string: waf / cc / acl | Yes | waf = WAF rule library, cc = CC protection, acl = access control. |
|---|
name | string | Yes | — |
|---|
description | string | Yes | — |
|---|
enabled | boolean | Yes | — |
|---|
default_action | string: allow / block | Yes | — |
|---|
rules | array<SecurityPolicyRuleInput> | Yes | — |
|---|
cc_settings | SecurityPolicyCCSettings | No | CC only. Site-level ban/pass durations (override every rule's) and the auto switch (自动切换). Omitted keeps the rules' own values. |
|---|
waf_settings | SecurityPolicyWAFSettings | No | WAF only (node CAPABILITY_NAME_WAF v2). Omitted (or defend mode without auto_block) is stored as absent. |
|---|
Responses
updateSecurityPolicy Responses| Status | Description |
|---|
200 | Policy replaced and version incremented, or an identical request replayed. Fields：kind: string: waf / cc / acl name: string description: string enabled: boolean default_action: string: allow / block rules: array<SecurityPolicyRuleInput> cc_settings?: SecurityPolicyCCSettings waf_settings?: SecurityPolicyWAFSettings id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null 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. |
|---|
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
DELETE /v1/security-policies/{id}
Soft-delete a policy using optimistic concurrency
- operationId
deleteSecurityPolicy- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.manage
Parameters
deleteSecurityPolicy Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Responses
deleteSecurityPolicy Responses| Status | Description |
|---|
204 | Policy soft-deleted, or an identical request replayed. |
|---|
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/security-policies/{id}/evaluate
Preview deterministic policy evaluation
- operationId
evaluateSecurityPolicy- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：security_policies.read
Description (from the contract)
Requires security_policies.read and an exact If-Match version. Conditions within a rule are ANDed; rules are ordered by ascending priority and UUID. continue preserves the current decision while evaluation continues, stop returns the terminal decision, and the policy default applies only when no rule matches. Preview does not publish configuration or prove edge enforcement.
Parameters
evaluateSecurityPolicy Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
evaluateSecurityPolicy Request body| Name | Type | Required | Description |
|---|
client_ip | any | any | Yes | — |
|---|
host | string | Yes | — |
|---|
path | string | Yes | — |
|---|
method | string | Yes | — |
|---|
headers | object | Yes | Header names are case-insensitive; arrays preserve repeated field values. Scalar values remain accepted for legacy clients. |
|---|
country | string | Yes | — |
|---|
asn | integer | Yes | — |
|---|
ja4 | string | Yes | — |
|---|
port | integer | Yes | — |
|---|
distinct_user_agents | integer | Yes | — |
|---|
status_404_count | integer | Yes | — |
|---|
Responses
evaluateSecurityPolicy Responses| Status | Description |
|---|
200 | Deterministic preview result for the requested policy version. Fields：policy_id: string(uuid) policy_version: integer(int64) action: string: allow / block / rate_limit / challenge / log / ban matched_rule_ids: array<string(uuid)> terminal_rule_id?: string(uuid) used_default: 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