Create your first allowlist
An allowlist is a whitelist of event types that Beacon accepts for a specific product and version. Without an allowlist, every event the SDK sends is accepted (subject to basic format checks). With an active allowlist, only the events you’ve listed are accepted; everything else is rejected to Invalid Events with the code ALLOWLIST_REJECTED.
When to use an allowlist
Allowlists are most useful once your application is past initial integration and you want stricter governance over what data flows in. Common reasons:
- Catch typos in production. A new release accidentally fires
report_exprotedinstead ofreport_exported. Without an allowlist, the typo silently joins your event stream and dilutes your reports. With an allowlist, it shows up in Invalid Events immediately. - Lock down a release. You’ve decided what events v2.0 of your application should send. An allowlist makes the contract explicit and rejects any event the engineering team didn’t sign off on.
- Govern multiple teams. When several engineers contribute to one application, an allowlist serves as the agreed list of “events we collectively measure” and prevents drift.
If you’re still iterating on what to track, allowlists add friction. Start without one; create one once your event taxonomy stabilizes.
How to get there
In the sidebar, expand Settings and click Allowlists. You’ll see a table of any existing allowlists in your organization, each tagged with a status badge:
- Staged (blue) — newly created, not yet governing events.
- Active (green) — currently governing events for its product and version.
- Archived (gray) — was active, but a newer allowlist has replaced it. Archived allowlists are kept for audit trail.
Step 1 — Open the create form
Click Create Allowlist in the top-right. You’re taken to a dedicated page (not a modal) with a form.
Step 2 — Fill in the form
| Field | Required | Notes |
|---|---|---|
| Product | Yes | The product (selected via the same Product Selector you’ve used elsewhere). The slug is what gets sent as source_app on events the allowlist will govern. |
| Version | Yes | A free-text version string. Must match exactly what your SDK is sending as source_version (e.g., 1.2.0, 2024.10-rc1, whatever convention you use). Allowlists are scoped to one specific version. |
| Entries | Yes (at least one) | The list of allowed events. Each entry is a category plus an event name. Click Add entry to add more rows; the trash icon removes a row. At least one entry is required. |
Submit when complete. You’re navigated to the new allowlist’s detail page.
Step 3 — The allowlist is staged, not active
Newly-created allowlists sit in staged status. Events flowing in are not yet checked against them. This is intentional — it lets you build and review the list before it starts rejecting traffic.
To make a staged allowlist govern events, click Activate on the detail page. A two-step impact preview shows you how many recent events would have been rejected if this allowlist had been active. Confirm to activate; cancel to keep editing.
Activation does two things at once:
- The target allowlist becomes Active.
- Any previously-active allowlist for the same product and version is moved to Archived. Only one allowlist can be active per product/version at a time.
Common questions
Can I delete an allowlist? Only when it’s in Staged status. Active and Archived allowlists are retained for audit; if you want to stop one from governing events, create a new one and activate it (which auto-archives the prior).
Can I edit a staged allowlist after creating it? Yes — the detail page has an Edit entries section. The same page also supports importing entries as JSON or CSV, and exporting entries as JSON.
My events are being rejected with ALLOWLIST_REJECTED.
That’s the active allowlist doing its job. Either add the missing event (category + name) to a new staged allowlist and activate it, or revisit whether the event is one you actually want to track.