API Keys

Understanding API Keys

API keys let a server-side sensor (the Node SDK, the PHP sensor, the WordPress plugin, or your own code) report to WebDecoy’s ingest service without a user login.

What an API key does not unlock

API keys authenticate the ingest endpoints that sensors report to (https://ingest.webdecoy.com/api/v1/...). They do not authenticate the dashboard API under /api/organizations/...; those routes require a signed-in user’s session token.

API Key Use Cases

Use Case	Description
SDK Authentication	@webdecoy/node and its framework adapters, or the PHP sensor
WordPress Plugin	Connect the plugin to your account
Custom Integrations	Send detections from your own code to the ingest API

API Key Format

WebDecoy API keys follow this format:

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

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 (/settings/api-keys)

2. Click “Create API Key”

   • The create key dialog opens

3. Configure the Key

   Field	Description
   Key Name	Descriptive name (e.g., “Production SDK”)
   Property Scope (Optional)	Limit to one property, or All Properties
   Scopes	What the key can access
   Expiration	Never, 30, 90 or 180 days, or 1 year

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
decoy-delivery:write	Report acknowledged decoy delivery from one explicitly selected property

New keys default to detections:read + detections:write. Detection, violation and AI referral endpoints require detections:write. The decoy delivery receipt endpoint requires decoy-delivery:write and a property belonging to the key’s organization; the key dialog and backend refuse an unbound delivery reporter. Select only that scope for a dedicated delivery key. See decoy delivery accounting.

Scope Recommendations

Use Case	Recommended Scopes
WordPress Plugin	detections:read, detections:write (the default)
Node SDK or PHP sensor	detections:read, detections:write (the default)
Controlled decoy response writer	decoy-delivery:write plus one registered property

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
Never	Permanent keys for production
30 days	Temporary testing
90 days	Short-term integrations
180 days	Semi-annual rotation
1 year	Annual rotation

---

Managing API Keys

Viewing API Keys

Click API Keys in the sidebar to see:

Column	Description
Name	Your key name, with an Expired or Revoked chip when that applies
Key	The key prefix, first 16 characters (for identification)
Scopes	Assigned permissions
Last Used	Most recent authenticated request
Created	Creation timestamp
Actions	Delete (revoke) the key

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 delete (trash) icon, Delete API key
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

---

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 of requests to the ingest API:

Authorization: Bearer sk_live_your_key_here

Example cURL (checks a key and returns its organization, property and scopes):

curl https://ingest.webdecoy.com/api/v1/auth/validate-key \
  -H "Authorization: Bearer sk_live_your_key_here"

In SDKs

// Node.js SDK
import { WebDecoy } from '@webdecoy/node';

const webdecoy = new WebDecoy({
  apiKey: process.env.WEBDECOY_API_KEY,
});

// PHP sensor (webdecoy/sensor)
use WebDecoy\Sensor\{Sensor, Config};

$sensor = new Sensor(new Config(
    apiKey: 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