API Keys

Understanding API Keys

API keys provide programmatic access to WebDecoy for SDKs, integrations, and custom applications. They authenticate requests to the WebDecoy API without requiring user login credentials.

API Key Use Cases

Use Case	Description
SDK Authentication	Node.js, PHP, or other SDKs
WordPress Plugin	Connect plugin to your account
Custom Integrations	Build your own tools
CI/CD Pipelines	Automated deployments
Monitoring Scripts	Detection alerting

API Key Format

WebDecoy API keys follow this format:

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

• sk_ - Secret key prefix
• live_ - Environment (live = production)
• xxxx... - 32-character unique identifier

Key Security

Aspect	Best Practice
Storage	Environment variables, not code
Access	Principle of least privilege
Rotation	Rotate periodically
Monitoring	Track key usage
Revocation	Revoke compromised keys immediately

---

Creating API Keys

Step-by-Step Guide

1. Navigate to API Keys

   • Click API Keys in the sidebar

2. Click “Create API Key”

   • The create key dialog opens

3. Configure the Key

   Field	Description
   Name	Descriptive name (e.g., “Production SDK”)
   Property	Optional: Limit to specific property
   Scopes	What the key can access
   Expiration	Optional: Auto-expire after X days

4. Click “Create”

   • The full API key is displayed
   • Copy it now - it won’t be shown again!

5. Store Securely

   • Add to your environment variables
   • Never commit to source control

Scopes

Scopes limit what an API key can do:

Scope	Permissions
detections:read	Read detection data
detections:write	Submit detections
domains:read	List domains
domains:write	Create/modify domains

These four are the only scopes; new keys default to detections:read + detections:write.

Scope Recommendations

Use Case	Recommended Scopes
WordPress Plugin	detections:read, detections:write
Monitoring Dashboard	detections:read
Node SDK (cloud mode)	detections:read, detections:write
Read-Only Reporting	detections:read, domains:read

Property Scoping

Optionally limit an API key to a specific property:

Setting	Behavior
No property (default)	Access to all organization resources
Specific property	Only that property’s data accessible

Use property scoping when:

• Different teams manage different properties
• Limiting blast radius of key compromise
• Client isolation (agencies)

Expiration

Set automatic expiration:

Setting	When to Use
No expiration	Permanent keys for production
30 days	Temporary testing
90 days	Short-term integrations
180 days	Semi-annual rotation
365 days	Annual rotation

---

Managing API Keys

Viewing API Keys

Click API Keys in the sidebar to see:

Column	Description
Name	Your key name
Key Prefix	First 16 characters (for identification)
Scopes	Assigned permissions
Last Used	Most recent API call
Created	Creation timestamp
Status	Active, Expired, or Revoked

Key Status

Status	Meaning
🟢 Active	Working normally
🟡 Expiring Soon	Expires within 30 days
🔴 Expired	Past expiration date
⚫ Revoked	Manually disabled

Identifying Keys

Since you can’t see the full key after creation, use:

• Name: Choose descriptive names
• Key Prefix: First 16 chars visible (e.g., sk_live_abc12345)
• Last Used: Timestamp helps identify active keys

Revoking API Keys

To revoke (permanently disable) a key:

1. Click API Keys in the sidebar
2. Find the key in the list
3. Click the Revoke button (or trash icon)
4. Confirm the revocation

What happens:

• Key stops working immediately
• All API calls with that key fail
• Key cannot be re-enabled
• Create a new key if needed

When to revoke:

• Key may be compromised
• Employee leaving
• Project completed
• Rotating keys

Key Rotation Best Practices

1. Create new key with same scopes
2. Update your application with new key
3. Test that new key works
4. Revoke old key after confirming
5. Document the rotation

Monitoring Key Usage

Track API key activity:

• Last Used column shows recent activity
• Inactive keys may indicate configuration issues
• Sudden spikes may indicate abuse

---

Using API Keys

In Environment Variables

# .env file
WEBDECOY_API_KEY=sk_live_your_key_here

Node.js

const apiKey = process.env.WEBDECOY_API_KEY;

// PHP
$apiKey = getenv('WEBDECOY_API_KEY');

In HTTP Requests

Include the API key in the Authorization header:

Authorization: Bearer sk_live_your_key_here

Example cURL:

curl -X GET https://api.webdecoy.com/api/organizations/123/detections \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json"

In SDKs

// Node.js SDK
const { WebDecoyClient } = require('webdecoy');

const client = new WebDecoyClient({
  apiKey: process.env.WEBDECOY_API_KEY
});

// PHP SDK
use WebDecoy\Client;

$client = new Client([
    'api_key' => getenv('WEBDECOY_API_KEY')
]);

---

API Key Security Checklist

Do’s

• Store keys in environment variables
• Use minimal required scopes
• Rotate keys periodically
• Revoke unused keys
• Use descriptive key names
• Monitor key usage
• Set expiration for temporary keys

Don’ts

• Commit keys to Git repositories
• Share keys in chat/email
• Use production keys in development
• Grant more scopes than needed
• Use same key for multiple purposes
• Ignore unused/old keys

If a Key Is Compromised

1. Revoke immediately - Don’t wait
2. Create new key with same scopes
3. Update applications with new key
4. Review logs for unauthorized access
5. Assess damage from compromised period