Skip to content
REST API · Shield

REST API

Shield API

Manage Edge Shield widgets and view protection stats under /api/shield.

On this page3 sections

All endpoints require authentication. Manage Edge Shield widgets here; token verification itself doesn’t happen on this API. Send verification requests to shield.edge.network as described in Server-side validation.

Create a widget#

Terminal
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:

JSON
{
  "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 sending a POST 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.

Something unclear or out of date? Tell us

View as Markdown Get support