# Allowed Events

> Configure which inbound events are routed to which destinations. Create allowed events, list them, change their destination membership, and delete them through the Ours Privacy REST API.

Source: https://docs.oursprivacy.com/docs/platform-api/allowed-events

Use this page to manage the allow list that gates which inbound events are dispatched to which destinations.

## Where this fits in the dispatch flow

Events flow through four stages on the way from a source to a destination:

Event dispatch flow: [Source](https://docs.oursprivacy.com/docs/platform-api/sources) → **Allowed Events (this page)** → [Data Governance](https://docs.oursprivacy.com/docs/platform-api/data-governance) → [Mappings](https://docs.oursprivacy.com/docs/platform-api/mappings) → [Destination](https://docs.oursprivacy.com/docs/platform-api/destinations)

Configuration changes at any stage take effect once you publish a [new version](https://docs.oursprivacy.com/docs/platform-api/versions).

Allowed Events is the first stage that can drop an event. An inbound event is matched against allowed events by `name`, **case-insensitively**. If no allowed event matches, the event is dropped and nothing downstream sees it. If a match is found, the event is routed only to the destinations listed in that allowed event's `destinationIds`. Everything that survives the allow-list stage then goes through [Data Governance](https://docs.oursprivacy.com/docs/platform-api/data-governance) and the destination's [Mappings](https://docs.oursprivacy.com/docs/platform-api/mappings) before dispatch.

## Naming rules

* `name` is trimmed when the allowed event is created. Inbound names are not trimmed, so they match only when they equal the stored name, ignoring case.
* Names starting with `$` are reserved for system events. `$identify` is the one system event you can allow.

## Adding and removing destinations

`destinationIds` is the second gate. An allowed event routes to **exactly** the destinations on its list, so a new destination receives an event once its ID is added to that event's list.

`PATCH /rest/v1/allowed-events/{id}` replaces `destinationIds` in full, so send every destination the event should keep.

## Operational signals

To check that an allowed event reaches its destinations, call [destination health](https://docs.oursprivacy.com/docs/platform-api/destinations) for each ID in `destinationIds`. A zero `successCount` while the event is firing means it is dropped before dispatch, usually by [Data Governance](https://docs.oursprivacy.com/docs/platform-api/data-governance) or a destination's [Mappings](https://docs.oursprivacy.com/docs/platform-api/mappings).

## GET /rest/v1/allowed-events

List every allowed event for this account. Allowed events sit between sources and destinations in the dispatch flow — only inbound events whose `event` field matches the `name` of an allowed event (case-insensitive) can be routed to that event's `destinationIds`. Events without a matching allowed event are dropped. The list is not paginated; the per-account count is bounded. System events (names beginning with `$`, e.g. `$heatmap_click`) are hidden from the response — only `$identify` is creatable as an allowed event. Requires API-key scope or current OAuth user permission: allowedEvent:list

Request URL: `GET https://app.oursprivacy.com/rest/v1/allowed-events`

Authentication: apiKey or oauth2.

### Responses

- `200`: List of allowed events
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entities` | object[] | Yes |  |
| `entities[].id` | string | Yes | Server-assigned UUID for this allowed event. |
| `entities[].name` | string | Yes | Case-insensitive event name. Inbound events whose `event` field matches this value are gated through this allowed event. Reserved: names starting with `$` are system events and cannot be created (except `$identify`). |
| `entities[].destinationIds` | string[] | Yes | Destinations that receive this event. Empty array means the event is allowed but routed nowhere (effectively dropped). PATCH replaces this list wholesale. |
| `entities[].trigger` | string \| null | No | Optional free-form trigger description. Not used by the dispatch pipeline — surfaced in the dashboard so teams can record where each event fires. |
| `entities[].createdAt` | string | Yes | ISO 8601 timestamp when the allowed event was created. |
| `entities[].updatedAt` | string \| null | No | ISO 8601 timestamp of the last PATCH. Equal to createdAt on a freshly created event. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## POST /rest/v1/allowed-events

Create a new allowed event for this account.

- `name` is required, trimmed, case-insensitively unique within the account, and rejected if it exceeds the platform event-name length limit.
- Names starting with `$` are reserved for system events. Only `$identify` is accepted.
- `destinationIds` is optional. Unknown ids and ids belonging to other accounts are silently filtered out at write time (the destination must exist on this account to be saved).

Returns the full entity so callers can read the server-assigned `id`, `createdAt`, and the filtered `destinationIds` without a follow-up GET. Known input failures (duplicate name, name length, `$`-prefix reservation, empty name) are returned as HTTP 409 with the reason in the response `error` field. Requires API-key scope or current OAuth user permission: allowedEvent:create

Request URL: `POST https://app.oursprivacy.com/rest/v1/allowed-events`

Authentication: apiKey or oauth2.

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `destinationIds` | string[] \| null | No |  |

### Responses

- `200`: Created allowed event
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `409`: Conflict — duplicate event name on this account, name too long, name starts with `$` (other than `$identify`), or empty name. Reason is in the response `error` field.
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Server-assigned UUID for this allowed event. |
| `name` | string | Yes | Case-insensitive event name. Inbound events whose `event` field matches this value are gated through this allowed event. Reserved: names starting with `$` are system events and cannot be created (except `$identify`). |
| `destinationIds` | string[] | Yes | Destinations that receive this event. Empty array means the event is allowed but routed nowhere (effectively dropped). PATCH replaces this list wholesale. |
| `trigger` | string \| null | No | Optional free-form trigger description. Not used by the dispatch pipeline — surfaced in the dashboard so teams can record where each event fires. |
| `createdAt` | string | Yes | ISO 8601 timestamp when the allowed event was created. |
| `updatedAt` | string \| null | No | ISO 8601 timestamp of the last PATCH. Equal to createdAt on a freshly created event. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## GET /rest/v1/allowed-events/{id}

Fetch a single allowed event by id. Returns 404 when no record matches the supplied id or it belongs to a different account. Requires API-key scope or current OAuth user permission: allowedEvent:find

Request URL: `GET https://app.oursprivacy.com/rest/v1/allowed-events/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Responses

- `200`: Allowed event details
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Server-assigned UUID for this allowed event. |
| `name` | string | Yes | Case-insensitive event name. Inbound events whose `event` field matches this value are gated through this allowed event. Reserved: names starting with `$` are system events and cannot be created (except `$identify`). |
| `destinationIds` | string[] | Yes | Destinations that receive this event. Empty array means the event is allowed but routed nowhere (effectively dropped). PATCH replaces this list wholesale. |
| `trigger` | string \| null | No | Optional free-form trigger description. Not used by the dispatch pipeline — surfaced in the dashboard so teams can record where each event fires. |
| `createdAt` | string | Yes | ISO 8601 timestamp when the allowed event was created. |
| `updatedAt` | string \| null | No | ISO 8601 timestamp of the last PATCH. Equal to createdAt on a freshly created event. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## PATCH /rest/v1/allowed-events/{id}

Partially update an allowed event. Only the fields you send are changed; omitted fields keep their current value.

- `destinationIds` is replaced wholesale when sent — the canonical way to add or remove a destination is to fetch, modify the array, and PATCH it back. Stale ids (deleted destinations or destinations on another account) are silently filtered out at write time.
- `name` is subject to the same rules as create: case-insensitive uniqueness, length cap, `$`-prefix reservation.
- `trigger` accepts `null` to clear the existing value.

Returns the full entity. Known input failures (duplicate name, length, `$`-prefix, empty name) are returned as HTTP 409 with the reason in the response `error` field. Requires API-key scope or current OAuth user permission: allowedEvent:update

Request URL: `PATCH https://app.oursprivacy.com/rest/v1/allowed-events/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | No | New event name. Subject to the same rules as create: case-insensitive uniqueness within the account, max length enforced by the platform, and the `$`-prefix reservation (only `$identify` is allowed). Omit to leave the name unchanged. |
| `destinationIds` | string[] \| null | No | Destinations that should receive this event. Wholesale replacement — the sent list becomes the new value. Stale IDs (destinations from another account or deleted destinations) are silently filtered out at write time. Send `[]` to gate the event from every destination. |
| `trigger` | string \| null | No | Free-form trigger description shown in the dashboard. Send `null` to clear. Not used by the dispatch pipeline. |

### Responses

- `200`: Updated allowed event
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `409`: Conflict — name change collides with an existing allowed event on this account, name too long, name starts with `$` (other than `$identify`), or empty name. Reason is in the response `error` field.
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Server-assigned UUID for this allowed event. |
| `name` | string | Yes | Case-insensitive event name. Inbound events whose `event` field matches this value are gated through this allowed event. Reserved: names starting with `$` are system events and cannot be created (except `$identify`). |
| `destinationIds` | string[] | Yes | Destinations that receive this event. Empty array means the event is allowed but routed nowhere (effectively dropped). PATCH replaces this list wholesale. |
| `trigger` | string \| null | No | Optional free-form trigger description. Not used by the dispatch pipeline — surfaced in the dashboard so teams can record where each event fires. |
| `createdAt` | string | Yes | ISO 8601 timestamp when the allowed event was created. |
| `updatedAt` | string \| null | No | ISO 8601 timestamp of the last PATCH. Equal to createdAt on a freshly created event. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## DELETE /rest/v1/allowed-events/{id}

Delete an allowed event. After deletion, inbound events whose `event` field matches the deleted name are no longer routed and are dropped at the allow-list stage of the dispatch flow. Requires API-key scope or current OAuth user permission: allowedEvent:delete

Request URL: `DELETE https://app.oursprivacy.com/rest/v1/allowed-events/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Responses

- `200`: Deleted successfully
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).
