Operation details
GET /v1/firewall-actions/policy
Read the desired, active, and last-known-good firewall action policy
- operationId
getFirewallActionPolicy- 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：firewall.read
Parameters
getFirewallActionPolicy Parameters| Name | In | Type | Required | Description |
|---|
target_scope_id | query | string(uuid) | Yes | — |
|---|
site_id | query | string(uuid) | Yes | — |
|---|
Responses
getFirewallActionPolicy Responses| Status | Description |
|---|
200 | Desired, active, and LKG state Fields：normal_action: string: disconnect / return_page escalated_action: string: nftables engage_threshold: integer recover_threshold: integer recovery_windows: integer block_networks: array<string> trusted_proxies: array<string> trusted_crawlers: array<TrustedCrawler> return_page: ReturnPage id: string(uuid) tenant_scope_id: string(uuid) site_id: string(uuid) revision: integer active_revision: integer lkg_revision: integer deployment_state: string: pending / active / failed host_escalation: string: owned / shared_unsupported document_sha256: string created_at: string(date-time) updated_at: string(date-time) |
|---|
401 | Authentication required |
|---|
403 | Permission denied |
|---|
404 | Policy absent or outside actor scope |
|---|
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.404 The resource does not exist or belongs to another tenant.
↑ Back to list
PUT /v1/firewall-actions/policy
Create the next immutable firewall action policy candidate
- operationId
putFirewallActionPolicy- 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：firewall.manage
Parameters
putFirewallActionPolicy Parameters| Name | In | Type | Required | Description |
|---|
target_scope_id | query | string(uuid) | Yes | — |
|---|
site_id | query | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Request body
application/json · Required：Yes
putFirewallActionPolicy Request body| Name | Type | Required | Description |
|---|
normal_action | string: disconnect / return_page | Yes | — |
|---|
escalated_action | string: nftables | Yes | — |
|---|
engage_threshold | integer | Yes | — |
|---|
recover_threshold | integer | Yes | — |
|---|
recovery_windows | integer | Yes | — |
|---|
block_networks | array<string> | Yes | — |
|---|
trusted_proxies | array<string> | Yes | — |
|---|
trusted_crawlers | array<TrustedCrawler> | Yes | — |
|---|
return_page | ReturnPage | Yes | — |
|---|
Responses
putFirewallActionPolicy Responses| Status | Description |
|---|
200 | Immutable candidate accepted for publication Fields：normal_action: string: disconnect / return_page escalated_action: string: nftables engage_threshold: integer recover_threshold: integer recovery_windows: integer block_networks: array<string> trusted_proxies: array<string> trusted_crawlers: array<TrustedCrawler> return_page: ReturnPage id: string(uuid) tenant_scope_id: string(uuid) site_id: string(uuid) revision: integer active_revision: integer lkg_revision: integer deployment_state: string: pending / active / failed host_escalation: string: owned / shared_unsupported document_sha256: string created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | Invalid policy or request metadata |
|---|
401 | Authentication required |
|---|
403 | Permission denied |
|---|
409 | Revision, idempotency, or LKG conflict |
|---|
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
POST /v1/firewall-actions/policy/recover
Create a monotonic recovery candidate from the last-known-good policy
- operationId
recoverFirewallActionLKG- 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：firewall.manage
Description (from the contract)
Creates a new monotonic candidate from the durable last-known-good document; it never rewinds revisions.
Parameters
recoverFirewallActionLKG Parameters| Name | In | Type | Required | Description |
|---|
target_scope_id | query | string(uuid) | Yes | — |
|---|
site_id | query | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Request body
application/json · Required：Yes
Responses
recoverFirewallActionLKG Responses| Status | Description |
|---|
200 | LKG recovery candidate accepted Fields：normal_action: string: disconnect / return_page escalated_action: string: nftables engage_threshold: integer recover_threshold: integer recovery_windows: integer block_networks: array<string> trusted_proxies: array<string> trusted_crawlers: array<TrustedCrawler> return_page: ReturnPage id: string(uuid) tenant_scope_id: string(uuid) site_id: string(uuid) revision: integer active_revision: integer lkg_revision: integer deployment_state: string: pending / active / failed host_escalation: string: owned / shared_unsupported document_sha256: string created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | Invalid policy or request metadata |
|---|
401 | Authentication required |
|---|
403 | Permission denied |
|---|
409 | Revision, idempotency, or LKG conflict |
|---|
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