Operation details
GET /v1/security-string-sets
List string sets
- operationId
listSecurityStringSets- 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 sets (writable) and the platform sets (read only, platform true). Items carry no entries; reference_count counts the tenant's live policies referencing the set.
Responses
listSecurityStringSets Responses| Status | Description |
|---|
200 | Sets ordered own first, then by name. Fields：items: array<SecurityStringSetSummary> |
|---|
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-string-sets
Create a string set
- operationId
createSecurityStringSet- 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 trimmed, deduplicated and byte ordered (A-Z lower-cased when not case sensitive); a refused entry is validation_error with details.field entries[i] and a reason (too_long, invalid_utf8, control_character, wildcard_too_many_stars, wildcard_only_wildcards, empty); the set as a whole entries with too_many_entries or too_large. match_mode and case_sensitive cannot change later. At most 200 live sets per scope (422 string_set_limit). Audit security.string_set.create.
Parameters
createSecurityStringSet Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createSecurityStringSet Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
description | string | No | — |
|---|
match_mode | string: exact / prefix / suffix / contains / wildcard | Yes | Fixed at creation. prefix compares bytes (/api also matches /apiary); wildcard: * any bytes, ? one byte, at most 3 * and 2000 entries. |
|---|
case_sensitive | boolean | Yes | Fixed at creation. When false A-Z are lower-cased (other letters compare as they are). |
|---|
entries | array<string> | Yes | At most 256 KiB together. |
|---|
Responses
createSecurityStringSet Responses| Status | Description |
|---|
201 | Created, or an identical request replayed. Fields：id: string(uuid) name: string description: string match_mode: string: exact / prefix / suffix / contains / wildcard case_sensitive: boolean entry_count: integer reference_count: integer revision: integer platform: boolean updated_at: string(date-time) entries: array<string> |
|---|
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. |
|---|
422 | The request is well formed but breaks a business rule (error.code names it). |
|---|
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-string-sets/{set_id}
Get a string set
- operationId
getSecurityStringSet- 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. An own or platform set, with its canonical entries.
Parameters
getSecurityStringSet Parameters| Name | In | Type | Required | Description |
|---|
set_id | path | string(uuid) | Yes | — |
|---|
Responses
getSecurityStringSet Responses| Status | Description |
|---|
200 | The set. Fields：id: string(uuid) name: string description: string match_mode: string: exact / prefix / suffix / contains / wildcard case_sensitive: boolean entry_count: integer reference_count: integer revision: integer platform: boolean updated_at: string(date-time) entries: array<string> |
|---|
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
PUT /v1/security-string-sets/{set_id}
Replace a string set
- operationId
updateSecurityStringSet- 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; match_mode / case_sensitive in the body are refused. Every tenant whose bound WAF policy references the set is republished automatically (system trigger string_set). Audit security.string_set.update.
Parameters
updateSecurityStringSet Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
set_id | path | string(uuid) | Yes | — |
|---|
Request body
application/json · Required：Yes
updateSecurityStringSet Request body| Name | Type | Required | Description |
|---|
expected_revision | integer | Yes | — |
|---|
name | string | Yes | — |
|---|
description | string | No | — |
|---|
entries | array<string> | Yes | — |
|---|
Responses
updateSecurityStringSet Responses| Status | Description |
|---|
200 | Replaced (revision + 1), or an identical request replayed. Fields：id: string(uuid) name: string description: string match_mode: string: exact / prefix / suffix / contains / wildcard case_sensitive: boolean entry_count: integer reference_count: integer revision: integer platform: boolean updated_at: string(date-time) entries: array<string> |
|---|
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-string-sets/{set_id}
Delete a string set
- operationId
deleteSecurityStringSet- 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 set any live policy version references is refused (409 string_set_in_use). Audit security.string_set.delete.
Parameters
deleteSecurityStringSet Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
set_id | path | string(uuid) | Yes | — |
|---|
expected_revision | query | integer | Yes | — |
|---|
Responses
deleteSecurityStringSet 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
GET /v1/security-string-sets/{set_id}/references
List the policies referencing a string set
- operationId
listSecurityStringSetReferences- 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. The caller's live policies with a version referencing the set (the platform sees every scope); rule_count is from the latest referencing version.
Parameters
listSecurityStringSetReferences Parameters| Name | In | Type | Required | Description |
|---|
set_id | path | string(uuid) | Yes | — |
|---|
Responses
listSecurityStringSetReferences Responses| Status | Description |
|---|
200 | Policies by name. Fields：items: array<SecurityStringSetReference> |
|---|
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