Shield API

Manage Edge Shield widgets and view protection stats under /api/shield. Note that token verification itself doesn't happen here — send verification requests to shield.edge.network as described in Server-Side Validation.

Create a Widget

curl -X POST https://edge.network/api/shield/widgets \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing site",
    "hostnames": ["example.com", "www.example.com"],
    "mode": "managed",
    "agentPolicy": "challenge"
  }'

# Response (201) — the secret is shown only once
{
  "widget": {
    "id": "wgt_abc123",
    "name": "Marketing site",
    "sitekey": "sk_...",
    "secretPrefix": "ss_...",
    "hostnames": ["example.com", "www.example.com"],
    "mode": "managed",
    "agentPolicy": "challenge",
    "shadow": false,
    "tarpit": false
  },
  "secret": "ss_live_...",
  "message": "Save the secret now — it will not be shown again."
}

Field	Required	Description
name	Yes	Display name for the widget
hostnames	No	Hostnames the sitekey may be used on
mode	No	Widget mode — see Widget Modes
agentPolicy	No	`allow`, `challenge`, or `block` — how verified agents are treated
shadow	No	Shadow mode — score traffic without enforcing
tarpit	No	Slow down suspected bots instead of failing fast

Widget Management

Endpoint	Description
GET /api/shield/widgets	List widgets
POST /api/shield/widgets	Create — returns the widget and its secret (once)
PATCH /api/shield/widgets/:widgetId	Update any subset of `name`, `hostnames`, `mode`, `agentPolicy`, `shadow`, `tarpit`
DELETE /api/shield/widgets/:widgetId	Revoke a widget — its sitekey and secret stop working
GET /api/shield/widgets/:widgetId/stats?hours=24	Hourly challenge/verify stats plus anomaly detection (up to 720 hours)
GET \| POST /api/shield/widgets/:widgetId/examine	Fetch / run the Shield Examiner AI analysis

Verifying Tokens

Widget creation gives you a sitekey (public, rendered in the browser widget) and a secret (server-side). Verify tokens by POSTing to the Shield service directly — https://shield.edge.network/siteverify — or verify offline with our published JWKS keys. See Server-Side Validation and Offline Verification.