User Attributes for Embedding

User attributes are key-value pairs that describe the person viewing an embedded dashboard – their tenant, role, region, plan tier, or any other dimension relevant to what they should see and how. The host application sets these attributes, typically as claims inside a JWT token, and the BI tool reads them to control data access, filter defaults, and feature visibility.

A single dashboard definition can serve thousands of users across hundreds of tenants. User attributes are the mechanism that makes this work. They turn one template into many personalized experiences without duplicating anything.

What user attributes control

User attributes feed into several layers of the embedded analytics experience:

Data access. A tenant_id attribute drives row-level security filters. When a user from Acme Corp loads the dashboard, the BI tool injects WHERE tenant_id = 'acme' into every query. The user sees only their organization's data. This is the most critical use of user attributes – it's a security control rather than a convenience.

Dashboard visibility. A role attribute determines which dashboards or tabs a user can access. An admin might see operational dashboards and configuration panels. A regular user sees only the analytics views relevant to their workflow. The BI tool evaluates the attribute and shows or hides content accordingly.

Default filter values. A region attribute can pre-set geographic filters so a European sales manager sees EMEA data on load without manually selecting it. The user can still change filters if the dashboard allows it – but the starting state matches their context.

Feature flags. A plan_tier attribute can control whether a user sees advanced analytics features, export buttons, or drill-down capabilities. This lets you gate analytics features by pricing tier without building separate dashboards for each plan.

Security attributes vs. personalization attributes

The distinction matters. Some attributes enforce access rules that users must be unable to override. Others set convenient defaults that users can change.

Security attributes are non-negotiable. tenant_id, org_id, and role drive row-level security and dashboard access control. These attributes must be set server-side, validated by the BI tool, and enforced at query time. A user should never be able to modify, remove, or override them through the embedded interface.

Personalization attributes are preferences. default_region, preferred_currency, timezone, and date_range set the initial state of the dashboard. If a user wants to change the region filter, that's fine – no security boundary is crossed.

The implementation challenge is ensuring the BI tool treats these two categories differently. Security attributes should be locked – applied as immutable WHERE clauses that exist outside the user's control. Personalization attributes should be used as filter defaults that the user can adjust. Mixing them up – making a security attribute modifiable, or making a preference immutable – creates either a vulnerability or a poor user experience.

How attributes are passed

The standard delivery mechanism is JWT claims. The host application generates a token on the backend, embedding attributes as claim fields:

{
  "user_id": "u_8291",
  "tenant_id": "acme",
  "role": "manager",
  "region": "emea",
  "plan_tier": "enterprise",
  "exp": 1712764800
}

The BI tool parses these claims after verifying the token signature. Each claim maps to a user attribute that the BI tool's data model references – in row-level security rules, dashboard visibility conditions, and filter defaults.

Some BI tools also support passing attributes through URL parameters or API calls. These methods work for personalization attributes but should never carry security attributes, since URL parameters are visible in browser history and easily modified by end users.

One dashboard, many contexts

The power of user attributes is combinatorial. A dashboard with tenant-based RLS, role-based visibility, region-based defaults, and tier-based feature gating serves a large matrix of user contexts from a single definition. You maintain one dashboard. The attributes handle the variation.

This scales well. Adding a new tenant means no dashboard changes – the new tenant's users arrive with the correct attributes in their tokens, and the existing RLS rules and visibility conditions apply automatically. Adding a new attribute dimension – say, department-level filtering – means updating the data model and token generation instead of rebuilding dashboards from scratch.