Version 2.4.7.20261116085428 · latest

Value-added protection schemes protect-schemes

One scheme each for replay, data leak and web tamper protection (one per tenant; admins edit the platform scheme); saving also updates sites that follow the scheme, sites with their own settings are left alone; part of WAF Enhanced.

Pick an endpoint to see its example call on the right.

ProtectionAuthentication: User (some parameters admin only)10 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

GET/api/v2/protect-schemes/leakGet the data leak protection scheme

Authentication: User (some parameters admin only)

PUT/api/v2/protect-schemes/leakSave the data leak protection scheme

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
auto_joinobject The rule that sites newly entering the range join the scheme automatically; omitted when off.
customRequiredSiteLeakGuardCustom[] Custom regular expressions, at most 16.
detectRequiredSiteLeakGuardDetect Action per built-in pattern; omit a pattern to not check it.
enabledboolean Scheme master switch: when on, sites following the scheme use it; when off, those sites are turned off (their values kept) and the auto-join rule is paused. False if never saved.
excludeRequiredstring[] Path prefixes that are not checked (a trailing * is optional), at most 32.
expected_updated_atstring Optimistic lock - the updated_at as the caller read it (when null, i.e. never saved, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check.
observe_daysRequiredinteger Days a site observes when turned on by the scheme (record only, no action); 0 = act right away.
override_customboolean Omit or false only - sites with their own settings are left alone (counted in apply.skipped_custom); use reset to scheme to override them.
selectionobject Sites to add to the scheme this time; send only when the switch is on after saving and the range was changed. Omit to add no sites.
GET/api/v2/protect-schemes/replayGet the replay protection scheme

Authentication: User (some parameters admin only)

PUT/api/v2/protect-schemes/replaySave the replay protection scheme

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
actionReplayGuardAction Without a token or on replay: block = 403; challenge = JS challenge. Omitted = block.
Values ["block","challenge"]
app_saltstring Signing salt (app key, 32-byte hex); with app_sign on but no salt, signed headers are never accepted.
app_signboolean App signature check - requests carrying the signature headers are checked by signature, no token needed.
auto_joinobject The rule that sites newly entering the range join the scheme automatically; omitted when off.
bind_ipboolean Also bind the token to the client IP (a new IP invalidates it).
enabledboolean Scheme master switch: when on, sites following the scheme use it; when off, those sites are turned off (their values kept) and the auto-join rule is paused. False if never saved.
expected_updated_atstring Optimistic lock - the updated_at as the caller read it (when null, i.e. never saved, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check.
methodsReplayGuardMethod[] Protected methods; omitted = POST/PUT/PATCH/DELETE.
override_customboolean Omit or false only - sites with their own settings are left alone (counted in apply.skipped_custom); use reset to scheme to override them.
pathsReplayGuardPath[] Protected API paths, at most 64; empty = nothing protected.
selectionobject Sites to add to the scheme this time; send only when the switch is on after saving and the range was changed. Omit to add no sites.
ttl_sinteger Token lifetime in seconds, also used for signed-header timestamps; omitted = 120.
GET/api/v2/protect-schemes/tamperGet the web tamper protection scheme

Authentication: User (some parameters admin only)

PUT/api/v2/protect-schemes/tamperSave the web tamper protection scheme

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
actionRequiredReplayGuardAction Without a token or on replay: block = 403; challenge = JS challenge. Omitted = block.
Values ["block","challenge"]
auto_joinobject The rule that sites newly entering the range join the scheme automatically; omitted when off.
enabledboolean Scheme master switch: when on, sites following the scheme use it; when off, those sites are turned off (their values kept) and the auto-join rule is paused. False if never saved.
expected_updated_atstring Optimistic lock - the updated_at as the caller read it (when null, i.e. never saved, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check.
modeRequiredstring What counts as tampering: structure = structural changes only; full = any change to the page.
Values ["structure","full"]
observe_daysRequiredinteger Days a site observes when turned on by the scheme (record only, no action); 0 = act right away.
override_customboolean Omit or false only - sites with their own settings are left alone (counted in apply.skipped_custom); use reset to scheme to override them.
scopesRequiredSiteTamperScope[] Protected scopes, at most 50.
selectionobject Sites to add to the scheme this time; send only when the switch is on after saving and the range was changed. Omit to add no sites.
POST/api/v2/protect-schemes/{kind}/applyApply the scheme to sites in bulk

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
auto_joinobject The rule that sites newly entering the range join the scheme automatically; omitted when off.
dry_runboolean When true, only return the counts of what would happen; nothing is written.
Default false
modestring What counts as tampering: structure = structural changes only; full = any change to the page.
Values ["structure","full"]
override_customboolean Omit or false only - sites with their own settings are left alone (counted in apply.skipped_custom); use reset to scheme to override them.
selectionobject Sites to add to the scheme this time; send only when the switch is on after saving and the range was changed. Omit to add no sites.
GET/api/v2/protect-schemes/{kind}/sitesList the sites that have this protection set up

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
qstring Fuzzy search by domain or site name (case-insensitive).
statusProtectSchemeSiteStatus Filter by status.
Values ["enabled","disabled","pending","capture_failed"]
sourceProtectSiteSource Filter by source: scheme = follows the scheme; custom = set for the site alone (including turned off).
read-onlyValues ["scheme","custom"]
POST/api/v2/protect-schemes/{kind}/sites/bulkReset or turn off this protection for many sites

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
actionRequiredReplayGuardAction Without a token or on replay: block = 403; challenge = JS challenge. Omitted = block.
Values ["block","challenge"]
filterProtectSchemeSiteFilter The same filters as the list; expanded to a set of sites by the server.
idsinteger[] Site ids.

Value-added protection schemes object

FieldTypeDescription
actionReplayGuardAction Without a token or on replay: block = 403; challenge = JS challenge. Omitted = block.
Values ["block","challenge"]
app_saltstring Signing salt (app key, 32-byte hex); with app_sign on but no salt, signed headers are never accepted.
app_signboolean App signature check - requests carrying the signature headers are checked by signature, no token needed.
appliedinteger Sites written (to be written on dry_run).
applyobject Result of applying this save to sites (only in the save response).
auto_joinobject The rule that sites newly entering the range join the scheme automatically; omitted when off.
read-only
bind_ipboolean Also bind the token to the client IP (a new IP invalidates it).
countsProtectSchemeCounts Site counts among the sites visible to the caller: total, turned on, following the scheme, set alone, and excluded by plan.
read-only
customSiteLeakGuardCustom[] Custom regular expressions, at most 16.
demoted_sitesinteger Sites switched to their own settings with values kept because their owner lacks WAF Enhanced (only in the save response).
read-only
detectSiteLeakGuardDetect Action per built-in pattern; omit a pattern to not check it.
domainstring Primary domain (the site name when there is none).
dry_runboolean When true, only return the counts of what would happen; nothing is written.
Default false
enabledboolean Scheme master switch: when on, sites following the scheme use it; when off, those sites are turned off (their values kept) and the auto-join rule is paused. False if never saved.
read-only
excludestring[] Path prefixes that are not checked (a trailing * is optional), at most 32.
expected_updated_atstring Optimistic lock - the updated_at as the caller read it (when null, i.e. never saved, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check.
failedProtectSchemeFailure[] Sites that could not be handled, with the reason; at most 100.
failed_totalinteger Total sites that could not be handled (larger than failed when truncated).
filterProtectSchemeSiteFilter The same filters as the list; expanded to a set of sites by the server.
gateProtectSchemeGate WAF Enhanced status of the scheme owner (the tenant or the platform): full = editable; readonly and basic = may only be reduced.
read-onlyValues ["full","readonly","basic"]
idsinteger[] Site ids.
is_defaultboolean True when the scheme has never been saved and the settings are defaults (not stored); omitted once saved.
read-only
itemsReplaySchemeSuggestion[] Ordered by POST count descending, at most 3; empty when there is no data or ClickHouse is unavailable.
matchedinteger Sites in the range the caller can see.
methodsReplayGuardMethod[] Protected methods; omitted = POST/PUT/PATCH/DELETE.
modestring What counts as tampering: structure = structural changes only; full = any change to the page.
Values ["structure","full"]
observe_daysinteger Days a site observes when turned on by the scheme (record only, no action); 0 = act right away.
observe_untilinteger End of the observation period (Unix milliseconds); set only for leak protection that is on and still observing, null when expired, never observing, off, or for other protections.
override_customboolean Omit or false only - sites with their own settings are left alone (counted in apply.skipped_custom); use reset to scheme to override them.
ownerstring Owner username.
pathsReplayGuardPath[] Protected API paths, at most 64; empty = nothing protected.
scopesSiteTamperScope[] Protected scopes, at most 50.
selectionobject Sites to add to the scheme this time; send only when the switch is on after saving and the range was changed. Omit to add no sites.
site_idinteger Site id.
skipped_custominteger Sites left alone because they have their own settings (override_custom is false).
skipped_gateinteger Sites not written because their owner's WAF Enhanced is not full.
sourceProtectSiteSource Where the site's setting comes from: scheme = follows the scheme (changes when the scheme is saved); custom = set for this site alone (including turned off and rows migrated from before).
read-onlyValues ["scheme","custom"]
statusProtectSchemeSiteStatus Status of the site's setting: enabled; disabled; pending = on but the tamper baseline is still queued; capture_failed = on but baseline capture failed repeatedly and stopped retrying (the last two exist for web tamper protection only).
Values ["enabled","disabled","pending","capture_failed"]
tenant_idinteger Owner user id.
today_blockedinteger Block and error-page count today (UTC), excluding hits during the observation period (leak protection only, same basis as counts.today_blocked in the scheme response); null for other protections, or when ClickHouse is unavailable or the query fails.
today_hitsinteger Hits today (data leak protection = masked plus blocked outside the observation period, i.e. today_masked + today_blocked; web tamper protection = pages found tampered today); null for replay protection.
today_maskedinteger Masking count today (UTC), excluding hits during the observation period (leak protection only, same basis as counts.today_masked in the scheme response); null for other protections, or when ClickHouse is unavailable or the query fails.
ttl_sinteger Token lifetime in seconds, also used for signed-header timestamps; omitted = 120.
updated_atstring Version (null if never saved); use expected_updated_at on update.
read-only
updated_sitesinteger Sites following the scheme that this save updated (only in the save response).
read-only
will_changeinteger dry_run only: sites that would change for the mode (turned on or joined for enable, updated for update, turned off for disable).

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command