Write Keys

Write keys authenticate event sources when sending data to SignalSmith’s Events API. Each write key is associated with a specific source (web, mobile, server) and controls permissions and rate limits for that source.

What Is a Write Key?

A write key is a unique identifier that authenticates requests to the Events API. It is sent as the username in HTTP Basic authentication:

# Base64 encode the write key with an empty password
Authorization: Basic $(echo -n "your_write_key:" | base64)

Write keys are source-scoped — each key is tied to a named source that identifies where events are coming from. This lets you:

• Track which source generated each event
• Apply different rate limits per source
• Revoke access for a specific source without affecting others
• Monitor event volume and errors by source

Creating a Write Key

Via the UI

1. Navigate to Events in the left sidebar
2. Click the Write Keys tab
3. Click Create Write Key
4. Fill in the configuration:

5. Click Create
6. Copy the write key immediately — it is only shown once at creation time

Via the API

curl -X POST https://your-workspace.signalsmith.dev/api/v1/events/write-keys \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Web App",
    "source_type": "web",
    "rate_limit_eps": 500,
    "allowed_event_types": ["track", "identify", "page"],
    "allowed_origins": ["https://app.example.com", "https://staging.example.com"]
  }'

Response:

{
  "id": "wk_abc123",
  "name": "Web App",
  "key": "sk_live_a1b2c3d4e5f6...",
  "source_type": "web",
  "rate_limit_eps": 500,
  "allowed_event_types": ["track", "identify", "page"],
  "allowed_origins": ["https://app.example.com", "https://staging.example.com"],
  "status": "active",
  "created_at": "2025-03-15T10:00:00Z"
}

The key field is only included in the creation response. Store it securely.

Managing Write Keys

Listing Write Keys

View all write keys in the Events > Write Keys tab. Each key shows:

• Name and source type
• Status (active, revoked)
• Creation date
• Last event received timestamp
• Event volume (last 24 hours)

Rotating a Write Key

To rotate a key (generate a new key while keeping the configuration):

1. Click the key you want to rotate
2. Click Rotate Key
3. A new key is generated and displayed — copy it immediately
4. The old key enters a grace period (default: 24 hours) during which both old and new keys are accepted
5. After the grace period, the old key is automatically revoked

This allows you to update your application code with the new key without downtime.

# Rotate via API
POST /api/v1/events/write-keys/{id}/rotate
{
  "grace_period_hours": 24
}

Revoking a Write Key

To immediately stop accepting events from a key:

1. Click the key you want to revoke
2. Click Revoke
3. Confirm the revocation

Revoked keys return 401 Unauthorized for all subsequent requests. Revocation is immediate and cannot be undone — you must create a new key.

# Revoke via API
POST /api/v1/events/write-keys/{id}/revoke

Permissions and Restrictions

Allowed Event Types

Restrict which event types a key can send. If a key is configured with allowed_event_types: ["track", "page"], any identify or group calls using that key will be rejected with 403 Forbidden.

This is useful for browser-side keys where you want to prevent client-side code from sending identify calls (which might overwrite server-set traits).

Allowed Origins

For browser-based (web) sources, configure CORS origins to prevent unauthorized sites from using your write key:

• Events from allowed origins are accepted
• Events from disallowed origins receive a CORS error
• Server-side requests (without an Origin header) bypass origin checks

Rate Limits

Each write key has a rate limit (events per second). Configure this based on expected volume:

When the rate limit is exceeded, events receive 429 Too Many Requests. The response includes a Retry-After header.

Security Best Practices

• Never expose server-side keys in client code — Server write keys should only be used in backend services. Use a separate web or mobile key for browser/app code.
• Use allowed origins for web keys — Prevent key theft by restricting which domains can use the key.
• Rotate keys regularly — Rotate write keys at least quarterly, or immediately if you suspect a key has been compromised.
• Restrict event types per key — Only allow the event types each source actually needs.
• Monitor for anomalies — Watch for unexpected spikes in event volume or events from unknown sources. The event debugger can help.

Troubleshooting