API Reference Summary
Quick reference for key WebDecoy API endpoints.
Overview
Section titled “Overview”The WebDecoy API uses REST architecture with JSON payloads. All endpoints require authentication via Bearer token (API key or Auth0 JWT).
Base URL
Section titled “Base URL”https://api.webdecoy.com/apiAuthentication
Section titled “Authentication”Authorization: Bearer sk_live_your_api_keyOr for user sessions:
Authorization: Bearer <auth0_jwt_token>Authentication Endpoints
Section titled “Authentication Endpoints”Callback (Complete Auth0 Login)
Section titled “Callback (Complete Auth0 Login)”POST /auth/callbackAuthorization: Bearer <auth0_jwt>Response:
{ "id": "user-uuid", "auth0_id": "auth0|123", "email": "user@example.com", "name": "User Name"}Get Current User
Section titled “Get Current User”GET /auth/meAuthorization: Bearer <token>Organizations
Section titled “Organizations”Create Organization
Section titled “Create Organization”POST /organizationsAuthorization: Bearer <token>
{ "name": "My Organization"}List Organizations
Section titled “List Organizations”GET /organizations?page=1&page_size=50Authorization: Bearer <token>Get Organization
Section titled “Get Organization”GET /organizations/{organization_id}Authorization: Bearer <token>Update Organization
Section titled “Update Organization”PUT /organizations/{organization_id}Authorization: Bearer <token>
{ "name": "Updated Name"}Properties
Section titled “Properties”Create Property
Section titled “Create Property”POST /organizations/{organization_id}/propertiesAuthorization: Bearer <token>
{ "name": "Production Website"}List Properties
Section titled “List Properties”GET /organizations/{organization_id}/properties?page=1&page_size=50Authorization: Bearer <token>Get Property
Section titled “Get Property”GET /properties/{property_id}Authorization: Bearer <token>Custom Domains
Section titled “Custom Domains”Create Domain
Section titled “Create Domain”POST /organizations/{organization_id}/domainsAuthorization: Bearer <token>
{ "domain": "decoy.example.com", "record_type": "A"}List Domains
Section titled “List Domains”GET /organizations/{organization_id}/domainsAuthorization: Bearer <token>Verify Domain
Section titled “Verify Domain”POST /domains/{domain_id}/verifyAuthorization: Bearer <token>Request SSL Certificate
Section titled “Request SSL Certificate”POST /domains/{domain_id}/ssl/requestAuthorization: Bearer <token>Check SSL Status
Section titled “Check SSL Status”POST /domains/{domain_id}/ssl-statusAuthorization: Bearer <token>Decoys
Section titled “Decoys”Create Decoy
Section titled “Create Decoy”POST /decoysAuthorization: Bearer <token>
{ "custom_domain_id": "domain-uuid", "name": "Admin Backup Trap", "path": "/admin/backup.zip", "trigger_action": "log", "decoy_type": "link"}List Decoys
Section titled “List Decoys”GET /decoys?page=1&page_size=50Authorization: Bearer <token>Get Decoy
Section titled “Get Decoy”GET /decoys/{decoy_id}Authorization: Bearer <token>Update Decoy
Section titled “Update Decoy”PATCH /decoys/{decoy_id}Authorization: Bearer <token>
{ "name": "Updated Name", "trigger_action": "block"}Delete Decoy
Section titled “Delete Decoy”DELETE /decoys/{decoy_id}Authorization: Bearer <token>Bot Scanners
Section titled “Bot Scanners”Create Bot Scanner
Section titled “Create Bot Scanner”POST /organizations/{organization_id}/bot-scannersAuthorization: Bearer <token>
{ "name": "Main Scanner", "enabled": true, "sensitivity": "medium"}List Bot Scanners
Section titled “List Bot Scanners”GET /organizations/{organization_id}/bot-scannersAuthorization: Bearer <token>Get Scanner Snippet
Section titled “Get Scanner Snippet”GET /organizations/{organization_id}/bot-scanners/{scanner_id}/snippetAuthorization: Bearer <token>Toggle Scanner
Section titled “Toggle Scanner”PATCH /organizations/{organization_id}/bot-scanners/{scanner_id}/toggleAuthorization: Bearer <token>Detections
Section titled “Detections”List Detections
Section titled “List Detections”GET /organizations/{organization_id}/detections?page=1&page_size=50Authorization: Bearer <token>Query Parameters:
| Parameter | Description |
|---|---|
property_id | Filter by property |
source | Detection source (decoy_link, endpoint, bot_scanner) |
min_bot_score | Minimum bot score |
max_bot_score | Maximum bot score |
country | Country code(s) |
is_proxy | true/false |
is_vpn | true/false |
is_tor | true/false |
start_date | ISO 8601 date |
end_date | ISO 8601 date |
sort_by | timestamp, bot_score |
sort_order | asc, desc |
Get Detection
Section titled “Get Detection”GET /organizations/{organization_id}/detections/{detection_id}Authorization: Bearer <token>Get Detection Stats
Section titled “Get Detection Stats”GET /organizations/{organization_id}/detections/statsAuthorization: Bearer <token>Get Hourly Stats
Section titled “Get Hourly Stats”GET /organizations/{organization_id}/detections/stats/hourlyAuthorization: Bearer <token>Get Filter Options
Section titled “Get Filter Options”GET /organizations/{organization_id}/detections/filter-optionsAuthorization: Bearer <token>MITRE ATT&CK
Section titled “MITRE ATT&CK”List Tactics
Section titled “List Tactics”GET /mitre/tacticsGet Tactic Stats
Section titled “Get Tactic Stats”GET /organizations/{organization_id}/mitre/statsAuthorization: Bearer <token>Integrations
Section titled “Integrations”Cloudflare
Section titled “Cloudflare”Create Integration
Section titled “Create Integration”POST /organizations/{organization_id}/integrations/cloudflareAuthorization: Bearer <token>
{ "api_token": "cloudflare_token", "account_id": "account_id", "zone_id": "zone_id", "zone_name": "example.com"}Create Blocking Rule
Section titled “Create Blocking Rule”POST /organizations/{organization_id}/integrations/cloudflare/rulesAuthorization: Bearer <token>
{ "decoy_id": "decoy-uuid", "rule_type": "block_all"}Webhooks
Section titled “Webhooks”Create Webhook
Section titled “Create Webhook”POST /organizations/{organization_id}/integrations/webhooksAuthorization: Bearer <token>
{ "name": "My Webhook", "url": "https://example.com/webhook", "on_detection": true, "min_bot_score": 70}Test Webhook
Section titled “Test Webhook”POST /organizations/{organization_id}/integrations/webhooks/{webhook_id}/testAuthorization: Bearer <token>API Keys
Section titled “API Keys”Create API Key
Section titled “Create API Key”POST /organizations/{organization_id}/api-keysAuthorization: Bearer <token>
{ "name": "Production SDK", "scopes": ["detections:read", "detections:write"], "expires_in": 365}Response:
{ "id": "key-uuid", "name": "Production SDK", "api_key": "sk_live_xxxxxxx", "key_prefix": "sk_live_xxx", "scopes": ["detections:read", "detections:write"]}Important: The full
api_keyis only returned once. Store it securely.
List API Keys
Section titled “List API Keys”GET /organizations/{organization_id}/api-keysAuthorization: Bearer <token>Revoke API Key
Section titled “Revoke API Key”DELETE /organizations/{organization_id}/api-keys/{key_id}Authorization: Bearer <token>Billing
Section titled “Billing”Get Plans
Section titled “Get Plans”GET /billing/plansAuthorization: Bearer <token>Create Checkout Session
Section titled “Create Checkout Session”POST /billing/checkout-sessionAuthorization: Bearer <token>
{ "organization_id": "org-uuid", "price_id": "price_xxx", "success_url": "https://app.example.com/billing/success", "cancel_url": "https://app.example.com/billing"}Get Subscription
Section titled “Get Subscription”GET /organizations/{organization_id}/subscriptionAuthorization: Bearer <token>Get Usage
Section titled “Get Usage”GET /organizations/{organization_id}/billing/usageAuthorization: Bearer <token>Response Formats
Section titled “Response Formats”Success Response
Section titled “Success Response”{ "data": { ... }, "total": 100, "page": 1, "page_size": 50}Error Response
Section titled “Error Response”{ "error": "Error message", "code": "ERROR_CODE", "status": 400}Common Status Codes
Section titled “Common Status Codes”| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Rate Limited |
| 500 | Server Error |
Rate Limits
Section titled “Rate Limits”| Endpoint Type | Limit |
|---|---|
| Read operations | 100/minute |
| Write operations | 30/minute |
| Detection submission | 1000/minute |
Rate limit headers:
X-RateLimit-Limit: 100X-RateLimit-Remaining: 95X-RateLimit-Reset: 1642680000