Embed portal - Identity & Workspace Settings

BETA FEATURE

This is a Beta feature. The documentation and feature may change rapidly.

You can request Beta access and try it out.

Introduction

Identity & workspace settings enable two critical capabilities for embedded analytics:

• Create Boundaries for User-Generated Content: When you enable self-service analytics (users creating their own dashboards), you need clear boundaries:
  • Personal boundaries: Each user gets their own private space for individual dashboards
  • Organization boundaries: Team members can collaborate on shared dashboards, but different organizations remain completely isolated
  • Permission boundaries: Control who can view vs. edit vs. create dashboards in organization's shared workspace

• Audit & Track User Activity: When you add embed_user_id and embed_org_id, Holistics can identify who the user is and log their activities, allowing you to:
  • User identification: Know which specific user performed each action
  • Organization tracking: See which organization each user belongs to in the logs
  • Activity logging: Track user interactions and dashboard creation with proper attribution

To enable these capabilities, you specify user and organization identity in your embed payload:

const embed_payload = {
  
  // identify embed user
  "embed_user_id": "user_id_1",
  
  // user "user_id_1" in "organization_id_1" organization
  "embed_org_id": "organization_id_1",
  
  // grant them permission -> what they can do
  "permissions": {
  
    // specify role of user "user_id_1" in "organization_id_1" shared workspace
    "org_workspace_role": "no_access" | "viewer" | "editor"
    
    // allow "user_id_1" to save dashboard to their personal workspace
    "enable_personal_workspace": true | false
  }
  
}

Understanding Workspaces

Think of workspaces as different rooms where users can work on dashboards:

	Personal Workspace	Organization Shared Workspace
What it is	A private space where each user creates their own dashboards	A shared space where team members collaborate on dashboards
Who sees it	Only that specific user	All team members in that organization (with different permission levels)
Best for	When users need private analytics (like a personal expense tracker)	When teams need to work together on analytics (like a sales team dashboard)

Setting Up Your Embed Configuration

Option 1: Individual Users Only (B2C)

When to use: Your app serves individual consumers who need private dashboards

Example: A fitness app where each user tracks their personal workout data

const embed_payload = {
  "object_name": "embed_portal",
  "object_type": "EmbedPortal",
  
  // Tell us who this user is
  "embed_user_id": "user_1_id",
  
  // Give them permission to create personal dashboards
  "permissions": {    
    "enable_personal_workspace": true
  }
}

Note: You don't need to specify an organization ID for this setup.

Option 2: Business Users with Organizations (B2B)

When to use: Your app serves businesses with multiple users who may need to collaborate

Setup A: Personal Workspaces Only

Users get private workspaces but stay isolated within their organization.

const embed_payload = {
  "object_name": "embed_portal",
  "object_type": "EmbedPortal",
  
  // Tell us who this user is
  "embed_user_id": "user_1_id",
  
  // Tell us which organization they belong to
  "embed_org_id": "department_1",
  
  // Set their permissions
  "permissions": {
    // No access to shared team workspace
    "org_workspace_role": "no_access", // or "viewer" for read-only
    
    // Allow personal dashboard creation
    "enable_personal_workspace": true
  }
}

Example use case: A company app where each employee tracks their individual performance metrics privately.

Setup B: Team Collaboration

Users can work together on shared dashboards, plus optionally have personal space.

const embed_payload = {
  "object_name": "embed_portal",
  "object_type": "EmbedPortal",
  
  // Tell us who this user is
  "embed_user_id": "team_lead_1",
  
  // Tell us which organization they belong to
  "embed_org_id": "department_1",
  
  // Set their permissions
  "permissions": {
    // Choose their role in the shared workspace
    "org_workspace_role": "editor", // or "viewer" or "no_access"
    
    // Optionally allow personal workspace too
    "enable_personal_workspace": true // or false
  }
}

Example use case: A project management app where team leads create departmental dashboards that team members can view and collaborate on, while also having personal project tracking spaces.

Understanding Organization Roles

• no_access - Can't see the shared workspace at all
• viewer - Can view shared dashboards but can't create or edit them
• editor - Can create, edit, and delete dashboards in the shared workspace

Real-world example:

• Editors: Team managers who create department dashboards
• Viewers: Team members who use those dashboards for their daily work
• No access: Users who only need personal analytics

🔐 Important: How User Isolation works

Your data stays secure through workspace isolation

Personal workspaces are completely separate based on the combination of user ID + organization ID. This means:

• Same person, different organizations = Different personal workspaces
• No data mixing between organizations
• Clean separation for security and privacy

Example Scenario

Let's say John works for a company with multiple departments:

// John in the Marketing department
{
  embed_user_id: "[email protected]",
  embed_org_id: "marketing",
  permissions: { enable_personal_workspace: true }
}
// Result: John gets a personal workspace with his marketing dashboards

// John moves to the Sales department
{
  embed_user_id: "[email protected]", 
  embed_org_id: "sales",
  permissions: { enable_personal_workspace: true }
}
// Result: John gets a NEW personal workspace for sales
// His old marketing dashboards are completely separate and not accessible

This isolation ensures that sensitive data from different departments never mix.