Event Sources

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

What Is an Event Source?

An event source is a unique identifier that authenticates requests to the Events API. It is sent as the username in HTTP Basic authentication:

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

Event sources 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 an Event Source

Via the UI

1. Navigate to Streams in the left sidebar
2. Click the Event Sources tab
3. Click Create Event Source
4. Fill in the configuration:

5. Click Create
6. The full write key is visible in the Event Sources table. Click the copy icon next to any key to copy it to your clipboard. Write keys are public identifiers (embedded in client SDKs), so Zeotap does not mask them — there is no one-time reveal flow.

Via the API

curl -X POST https://composable.zeotap.com/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 Event Sources

Listing Event Sources

View all event sources in the Streams > Event Sources tab. Each entry shows:

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

Rotating an Event Source Key

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

1. Click the event source 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 an Event Source

To immediately stop accepting events from an event source:

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

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

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

Permissions and Restrictions

Allowed Event Types

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

This is useful for browser-side event sources 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 event source 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 event source 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 event source keys should only be used in backend services. Use a separate web or mobile event source for browser/app code.
• Use allowed origins for web event sources — Prevent key theft by restricting which domains can use the key.
• Rotate keys regularly — Rotate event source keys at least quarterly, or immediately if you suspect a key has been compromised.
• Restrict event types per event source — 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