Operation details
GET /v1/security-ip-lists
List named IP lists
- operationId
listSecurityIPLists- 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 security_policies.read. Tenant identities only: the tenant's own lists (writable) and the platform lists (read only, platform true).
Responses
listSecurityIPLists Responses| Status | Description |
|---|
200 | Lists ordered own first, then by name. Fields：items: array<SecurityIPList> |
|---|
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
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-ip-lists
Create a named IP list
- operationId
createSecurityIPList- 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 security_policies.manage. Entries are canonicalized (masked, deduplicated, ordered). Audit security.ip_list.create. At most 200 live lists per scope.
Parameters
createSecurityIPList Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createSecurityIPList Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
description | string | No | — |
|---|
entries | array<string> | Yes | — |
|---|
Responses
createSecurityIPList Responses| Status | Description |
|---|
201 | Created, or an identical request replayed. Fields：id: string(uuid) name: string description: string entries: array<string> revision: integer platform: boolean 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
PUT /v1/security-ip-lists/{list_id}
Replace a named IP list
- operationId
updateSecurityIPList- 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 security_policies.manage and the current revision. Every tenant whose bound WAF policy references the list is republished automatically (system trigger ip_list). Audit security.ip_list.update.
Parameters
updateSecurityIPList Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
list_id | path | string(uuid) | Yes | — |
|---|
Request body
application/json · Required：Yes
updateSecurityIPList Request body| Name | Type | Required | Description |
|---|
expected_revision | integer | Yes | — |
|---|
name | string | Yes | — |
|---|
description | string | No | — |
|---|
entries | array<string> | Yes | — |
|---|
Responses
updateSecurityIPList Responses| Status | Description |
|---|
200 | Replaced (revision + 1), or an identical request replayed. Fields：id: string(uuid) name: string description: string entries: array<string> revision: integer platform: boolean 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-ip-lists/{list_id}
Delete a named IP list
- operationId
deleteSecurityIPList- 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 security_policies.manage and the current revision. A list any live policy version references is refused (409 ip_list_in_use). Audit security.ip_list.delete.
Parameters
deleteSecurityIPList Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
list_id | path | string(uuid) | Yes | — |
|---|
expected_revision | query | integer | Yes | — |
|---|
Responses
deleteSecurityIPList Responses| Status | Description |
|---|
204 | 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. |
|---|
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