Permissions

Embed sessions support fine-grained permissions that control what each customer can see and do.

Concept map

Permissions are the policy layer on top of the signed tenant-scoped session and the browser runtime.

Data Events Permissions only make sense once the underlying event schema and dimensions are stable. Browser Embed Runtime The host page and dashboard still talk through the same runtime even when permissions narrow the surface. Isolation Tenants Permissions layer on top of tenant scope; they do not replace tenant isolation. Surface Dashboards Permissions narrow the published dashboard surface rather than redefining the dashboard model itself. Control Permissions How drill, hidden widgets, locked filters, and period limits stay bounded.

Embed session permissions

Pass a permissions object when creating an embed session:

{
  "tenant_id": "customer_1",
  "dashboard_id": "dash_abc",
  "expires_in": 3600,
  "permissions": {
    "allow_drill_down": true,
    "locked_filters": {"plan": "pro"},
    "hidden_widgets": ["internal_notes"],
    "allowed_dimensions": ["model", "endpoint"],
    "allowed_periods": ["7d", "30d"],
    "max_date_range_days": 30
  }
}

Permission fields

Field	Type	Default	Description
`allow_drill_down`	bool	true	Allow click-to-filter and detail drill-down
`locked_filters`	object	{}	Pre-applied filters the user cannot change
`allowed_dimensions`	string[]	all	Which filter dimensions are visible
`hidden_widgets`	string[]	[]	Widget IDs to remove from the embed surface
`allowed_periods`	string[]	all	Restrict the period options shown in the filter bar
`max_date_range_days`	number	0	Maximum allowed date range in days; `0` means unlimited

Common policy patterns

Most customer-facing permission setups are not arbitrary. They repeat a small number of practical patterns.

Pattern 1 Locked plan view Use locked_filters to keep the dashboard scoped to one commercial slice, such as {"plan":"pro"}, without exposing that filter to the customer.

Pattern 2 Internal-only widget Use hidden_widgets to remove finance, support, or ops-only blocks from the published customer surface while keeping one dashboard definition.

Pattern 3 No drill for executive views Set allow_drill_down: false when the customer should see a stable summary surface, not click deeper into operational data.

Pattern 4 Bounded period control Use allowed_periods and max_date_range_days to keep the UI simple and prevent expensive or misleading long-range queries.

Pattern 5 Dimension-safe filtering Use allowed_dimensions to expose only the customer-facing slice of the filter bar, even if the underlying dashboard knows about more dimensions.

Validation path: check Tenants first, then Embed Runtime. Permissions narrow an already tenant-scoped published surface; they do not replace tenant isolation or server-side session minting.

Locked filters

Use locked filters to restrict data without the customer knowing. For example, show only "pro" plan data:

"locked_filters": {"plan": "pro"}

The filter is applied at query time and the dimension is hidden from the filter bar.

API key scopes

Scope	Can do
`admin`	Everything: events, queries, dashboards, embed sessions, settings, API keys
`ingest`	Send events only. Cannot read data or manage resources.

Team roles

Role	Capabilities
`owner`	Full access + delete org + change member roles
`admin`	Full access + manage team + manage API keys
`editor`	Edit dashboards, view settings
`viewer`	View dashboards and data only