Shield API · v0.4.2

Customer-scoped edge protection

The panel provides Basic controls for every eligible KVM. The Account API façade is an Advanced feature. In both cases Atlas selects the owned destination, placement and interface; callers cannot override them.

Interactive Account OpenAPI TypeScript SDK

Ownership is enforced on every read and mutation.

A rule or rollback is scoped to the authenticated account, the selected service and its Atlas-assigned /32 or /128 address. Provider credentials and router identifiers stay backend-only. API calls return shield_advanced_required for Basic accounts.

Basic and Advanced limits

Basic is included with eligible KVM services. Advanced is account-wide and retains protection through a seven-day renewal grace period.

Capability	Basic	Advanced
Rules per IP	3 safe presets	30 custom rules
Rules per account	25	300
PPS/BPS limits	System managed	Up to 10 per IP
Analytics	24 hours · top 20	30 days · top 100
Protection history	7 days	30 days
Profiles	Off · Default	Off · Low · Default · Strict

Apply

POST mutations require shield:write and an Idempotency-Key. Reuse the same key and body when retrying.

Rollback and removal

DELETE queues a verified rollback for an applied rule. Provider objects are physically deleted only in draft, rejected or canceled pre-apply states; enforcement history remains auditable.

Lifecycle

At grace expiry rules are disabled and retained. Renewal can restore retained intent; infrastructure emergency controls are never changed.

Production dataplane contract

Atlas targets phylex-mitigate-v4-mixed. The router-local /v1/dataplane/v3 path is retained only as a wire-compatibility endpoint.

Before processing queued mutations, Atlas verifies that the Shield capability inventory advertises both the v4-mixed backend and native_protection_profiles. Shield then validates the selected router's live dataplane identity and requires name=v4-mixed with mode=enforce.

A Low, Default or Strict selection is one Atlas rule and one Shield UUID. Shield expands it transactionally into router-local TCP, UDP and ICMP/ICMPv6 components; those component IDs are diagnostic details and are not exposed as separate customer rules.

If the Atlas Shield module is administratively paused, endpoints return HTTP 503 with shield_module_disabled and a retry hint. Existing verified dataplane state is retained.

Apply a native protection profile

Advanced API example. Atlas derives the protected host and queues one parent policy; the profile components are managed by Shield.

curl --request POST \
  https://billing.phylex.net/api/proxy/account-api/v1/services/PHX-SVC-0000087A/shield/profiles/default \
  --header 'Authorization: Bearer phxak_REPLACE_WITH_YOUR_KEY' \
  --header 'Idempotency-Key: shield-profile-0191-example' \
  --header 'Content-Type: application/json' \
  --data '{}'

How traffic analytics is collected

Traffic analytics uses bounded 1:64 flow sampling and returns ranked aggregates, never packet payloads.

Low-volume traffic may legitimately produce an empty ranked window when it does not enter the edge heavy-hitter set. The panel reports that state explicitly and does not fabricate chart points.

Protection activity is separate: it uses exact deltas from customer-managed XDP rule counters and remains scoped to the selected owned destination.

Apply a safe preset

Advanced API example. The service reference is public; the protected IP is always derived by Atlas.

curl --request POST \
  https://billing.phylex.net/api/proxy/account-api/v1/services/PHX-SVC-0000087A/shield/presets/drop_tcp_null \
  --header 'Authorization: Bearer phxak_REPLACE_WITH_YOUR_KEY' \
  --header 'Idempotency-Key: shield-preset-0191-example' \
  --header 'Content-Type: application/json' \
  --data '{}'

Capability

Basic

Advanced

Rules per IP

3 safe presets

30 custom rules

Rules per account

300

PPS/BPS limits

System managed

Up to 10 per IP

Analytics

24 hours · top 20

30 days · top 100

Protection history

7 days

30 days

Profiles

Off · Default

Off · Low · Default · Strict

curl --request POST \ https://billing.phylex.net/api/proxy/account-api/v1/services/PHX-SVC-0000087A/shield/profiles/default \ --header 'Authorization: Bearer phxak_REPLACE_WITH_YOUR_KEY' \ --header 'Idempotency-Key: shield-profile-0191-example' \ --header 'Content-Type: application/json' \ --data '{}'

curl --request POST \ https://billing.phylex.net/api/proxy/account-api/v1/services/PHX-SVC-0000087A/shield/presets/drop_tcp_null \ --header 'Authorization: Bearer phxak_REPLACE_WITH_YOUR_KEY' \ --header 'Idempotency-Key: shield-preset-0191-example' \ --header 'Content-Type: application/json' \ --data '{}'