Operation details
GET /v1/security-bans
List the ban list of the session tenant's sites
- operationId
listSecurityBans- Auth
- 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
listSecurityBans Parameters| Name | In | Type | Required | Description |
|---|
site_id | query | string(uuid) | No | — |
|---|
client_ip | query | string | No | An address or a network. |
|---|
state | query | string: active / released / expired | No | — |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
Responses
listSecurityBans Responses| Status | Description |
|---|
200 | Newest first. Fields：items: array<Entry> total: integer page: integer limit: integer |
|---|
400 | Error. |
|---|
401 | Error. |
|---|
403 | Error. |
|---|
404 | Error. |
|---|
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
POST /v1/security-bans
Ban a client on a site of the session tenant
- operationId
createSecurityBan- Auth
- 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
createSecurityBan Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createSecurityBan Request body| Name | Type | Required | Description |
|---|
site_id | string(uuid) | Yes | — |
|---|
client_ip | string | Yes | An IPv4 / IPv6 address, or a network IPv4 /8../31, IPv6 /32../127 (nodes with BAN_CIDR). |
|---|
duration_seconds | integer | Yes | — |
|---|
reason | string | No | — |
|---|
Responses
createSecurityBan Responses| Status | Description |
|---|
201 | The ban. Fields：id: string(uuid) tenant_scope_id: string(uuid) site_id: string(uuid) site_domain: string client_ip: string source: string: waf / cc / manual / autodefense / market rule_id: string reason: string banned_at: string(date-time) banned_until: string(date-time) created_by: string(uuid) | null(uuid) released_at: string(date-time) | null(date-time) released_by: string(uuid) | null(uuid) state: string: active / released / expired market: null | MarketOrigin delivery: null | Delivery |
|---|
400 | Error. |
|---|
401 | Error. |
|---|
403 | Error. |
|---|
404 | Error. |
|---|
409 | Error. |
|---|
422 | Error. |
|---|
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-bans/{entry_id}/release
Release a ban of the session tenant
- operationId
releaseSecurityBan- Auth
- 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
releaseSecurityBan Parameters| Name | In | Type | Required | Description |
|---|
entry_id | path | string(uuid) | Yes | — |
|---|
Responses
releaseSecurityBan Responses| Status | Description |
|---|
200 | The ban. Fields：id: string(uuid) tenant_scope_id: string(uuid) site_id: string(uuid) site_domain: string client_ip: string source: string: waf / cc / manual / autodefense / market rule_id: string reason: string banned_at: string(date-time) banned_until: string(date-time) created_by: string(uuid) | null(uuid) released_at: string(date-time) | null(date-time) released_by: string(uuid) | null(uuid) state: string: active / released / expired market: null | MarketOrigin delivery: null | Delivery |
|---|
400 | Error. |
|---|
401 | Error. |
|---|
403 | Error. |
|---|
404 | Error. |
|---|
409 | Error. |
|---|
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