January 20268 min read

Workspaces

Organize your projects, sites, and team members with workspaces.

Overview

Workspaces are the top-level organizational unit in pxlpeak. They provide:

Isolation: Separate data, users, and billing between projects
Organization: Group related sites and team members
Access Control: Manage permissions at workspace and site levels
Billing: Independent subscription and usage tracking

code

┌─────────────────────────────────────────────────────────────────┐
│                        Organization                              │
│  (Your pxlpeak account)                                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │   Workspace A    │  │   Workspace B    │  │  Workspace C │  │
│  │   (Marketing)    │  │   (Client ABC)   │  │  (Personal)  │  │
│  ├──────────────────┤  ├──────────────────┤  ├──────────────┤  │
│  │ • Main Website   │  │ • abc.com        │  │ • blog.me    │  │
│  │ • Landing Pages  │  │ • shop.abc.com   │  │              │  │
│  │ • Mobile App     │  │ • app.abc.com    │  │              │  │
│  │                  │  │                  │  │              │  │
│  │ 5 team members   │  │ 3 team members   │  │ 1 member     │  │
│  │ Pro plan         │  │ Enterprise       │  │ Free plan    │  │
│  └──────────────────┘  └──────────────────┘  └──────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Creating a Workspace

Via Dashboard

Click Workspaces in the sidebar
Click Create Workspace
Enter workspace details:
- Name: Descriptive name (e.g., "Acme Corp Marketing")
- Slug: URL-friendly identifier (e.g., "acme-marketing")
- Timezone: Default timezone for reports
- Currency: Default currency for revenue

Via API

code

const response = await fetch('https://api.pxlpeak.com/v1/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Client Project',
    slug: 'client-project',
    timezone: 'America/New_York',
    currency: 'USD',
    settings: {
      data_retention_days: 730,
      ip_anonymization: true
    }
  })
});

const workspace = await response.json();
// { id: 'ws_xxx', name: 'Client Project', ... }

Workspace Structure

Sites

Sites are individual properties (websites, apps) within a workspace:

code

// Create a site in a workspace
const site = await pxlpeak.sites.create({
  workspaceId: 'ws_xxx',
  name: 'Main Website',
  domain: 'example.com',
  timezone: 'America/Los_Angeles', // Override workspace default
  settings: {
    tracking_enabled: true,
    cookie_consent_required: true,
    cross_domain_tracking: ['shop.example.com', 'blog.example.com']
  }
});

Site Hierarchy:

| Level | Description | Example | |-------|-------------|---------| | Workspace | Container for related sites | "Acme Corp" | | Site | Individual property | "Main Website" | | View | Filtered data subset | "Mobile Traffic Only" |

Views

Views provide filtered perspectives on site data:

code

// Create a filtered view
const view = await pxlpeak.views.create({
  siteId: 'site_xxx',
  name: 'US Mobile Traffic',
  filters: [
    { field: 'country', operator: 'eq', value: 'US' },
    { field: 'device_type', operator: 'eq', value: 'mobile' }
  ],
  permissions: {
    inherit_from_site: true
  }
});

Team Management

Inviting Members

code

// Invite a team member
await pxlpeak.workspaces.inviteMember({
  workspaceId: 'ws_xxx',
  email: 'colleague@example.com',
  role: 'editor',
  siteAccess: ['site_xxx', 'site_yyy'], // Or 'all' for full access
  message: 'Join our analytics workspace!'
});

Workspace Roles

| Role | Capabilities | |------|-------------| | Owner | Full control, billing, delete workspace | | Admin | Manage members, sites, settings | | Editor | Create/edit goals, segments, reports | | Analyst | View all data, create reports | | Viewer | View dashboards and reports only |

Role Permissions Matrix

code

Permission                 │ Owner │ Admin │ Editor │ Analyst │ Viewer
───────────────────────────┼───────┼───────┼────────┼─────────┼───────
View analytics             │   ✓   │   ✓   │   ✓    │    ✓    │   ✓
Create reports             │   ✓   │   ✓   │   ✓    │    ✓    │
Export data                │   ✓   │   ✓   │   ✓    │    ✓    │
Create goals/segments      │   ✓   │   ✓   │   ✓    │         │
Manage sites               │   ✓   │   ✓   │        │         │
Manage members             │   ✓   │   ✓   │        │         │
Workspace settings         │   ✓   │   ✓   │        │         │
Billing & subscription     │   ✓   │       │        │         │
Delete workspace           │   ✓   │       │        │         │

Managing Member Access

code

// Update member role
await pxlpeak.workspaces.updateMember({
  workspaceId: 'ws_xxx',
  memberId: 'member_yyy',
  role: 'admin',
  siteAccess: 'all'
});

// Remove member
await pxlpeak.workspaces.removeMember({
  workspaceId: 'ws_xxx',
  memberId: 'member_yyy'
});

// List members
const members = await pxlpeak.workspaces.listMembers({
  workspaceId: 'ws_xxx'
});

Workspace Settings

General Settings

code

// Update workspace settings
await pxlpeak.workspaces.update({
  workspaceId: 'ws_xxx',
  settings: {
    // Display settings
    name: 'Updated Workspace Name',
    timezone: 'Europe/London',
    currency: 'GBP',
    date_format: 'DD/MM/YYYY',

    // Privacy settings
    ip_anonymization: true,
    data_retention_days: 365,

    // Feature flags
    features: {
      cross_domain_tracking: true,
      enhanced_attribution: true,
      predictive_analytics: false
    },

    // Notifications
    notifications: {
      weekly_digest: true,
      alert_emails: ['alerts@example.com'],
      slack_webhook: 'https://hooks.slack.com/...'
    }
  }
});

Data Retention

Configure how long data is retained:

| Retention Period | Use Case | |------------------|----------| | 30 days | Testing, high-volume free tier | | 90 days | Standard analytics | | 365 days | Year-over-year analysis | | 730 days | Long-term trends (default) | | Unlimited | Enterprise, compliance needs |

code

// Update retention policy
await pxlpeak.workspaces.update({
  workspaceId: 'ws_xxx',
  settings: {
    data_retention_days: 365,
    retention_policy: {
      raw_events: 90,           // Detailed event data
      aggregated_data: 730,     // Daily/weekly summaries
      user_profiles: 365        // User identification data
    }
  }
});

Agency & Multi-Client Setup

White-Label Configuration

For agencies managing multiple client workspaces:

code

// Agency workspace with white-label settings
await pxlpeak.workspaces.update({
  workspaceId: 'ws_xxx',
  whiteLabel: {
    enabled: true,
    brandName: 'Agency Analytics',
    logoUrl: 'https://agency.com/logo.svg',
    primaryColor: '#4F46E5',
    customDomain: 'analytics.agency.com',
    removesBranding: true,
    customEmailDomain: 'analytics.agency.com'
  }
});

Client Workspace Structure

code

┌─────────────────────────────────────────────────────────────────┐
│                      Agency Organization                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    Agency Workspace                       │  │
│  │  (Internal use, all client access)                       │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │ • Agency Staff (Admin access to all)                     │  │
│  │ • Aggregated reporting                                   │  │
│  │ • Cross-client benchmarks                                │  │
│  └──────────────────────────────────────────────────────────┘  │
│                              │                                   │
│           ┌──────────────────┼──────────────────┐               │
│           ▼                  ▼                  ▼               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │  Client A    │  │  Client B    │  │  Client C    │         │
│  │  Workspace   │  │  Workspace   │  │  Workspace   │         │
│  ├──────────────┤  ├──────────────┤  ├──────────────┤         │
│  │ client-a.com │  │ client-b.com │  │ client-c.com │         │
│  │              │  │ shop-b.com   │  │              │         │
│  │              │  │              │  │              │         │
│  │ Client team: │  │ Client team: │  │ Client team: │         │
│  │ View only    │  │ View only    │  │ Analyst      │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Bulk Client Management

code

// Create client workspaces in bulk
async function createClientWorkspaces(clients: ClientInfo[]) {
  const results = [];

  for (const client of clients) {
    // Create workspace
    const workspace = await pxlpeak.workspaces.create({
      name: client.name,
      slug: client.slug,
      settings: {
        timezone: client.timezone,
        currency: client.currency
      }
    });

    // Create main site
    const site = await pxlpeak.sites.create({
      workspaceId: workspace.id,
      name: `${client.name} Website`,
      domain: client.domain
    });

    // Invite client team
    for (const contact of client.contacts) {
      await pxlpeak.workspaces.inviteMember({
        workspaceId: workspace.id,
        email: contact.email,
        role: 'viewer'
      });
    }

    // Add agency staff with admin access
    await pxlpeak.workspaces.inviteMember({
      workspaceId: workspace.id,
      email: 'team@agency.com',
      role: 'admin'
    });

    results.push({ workspace, site });
  }

  return results;
}

Cross-Workspace Features

Consolidated Reporting

View aggregated data across workspaces:

code

// Get cross-workspace summary
const summary = await pxlpeak.reports.crossWorkspace({
  workspaceIds: ['ws_xxx', 'ws_yyy', 'ws_zzz'],
  dateRange: {
    start: '2026-01-01',
    end: '2026-01-12'
  },
  metrics: ['sessions', 'conversions', 'revenue'],
  groupBy: 'workspace'
});

// Result:
// [
//   { workspace: 'Client A', sessions: 50000, conversions: 1200, revenue: 45000 },
//   { workspace: 'Client B', sessions: 30000, conversions: 800, revenue: 28000 },
//   { workspace: 'Client C', sessions: 20000, conversions: 500, revenue: 18000 }
// ]

Cross-Workspace Templates

Share configuration across workspaces:

code

// Create a template from existing workspace
const template = await pxlpeak.templates.create({
  sourceWorkspaceId: 'ws_xxx',
  name: 'E-commerce Standard',
  include: {
    goals: true,
    segments: true,
    dashboards: true,
    alerts: true
  }
});

// Apply template to new workspace
await pxlpeak.templates.apply({
  templateId: template.id,
  targetWorkspaceId: 'ws_new'
});

Workspace API Reference

List Workspaces

code

GET /v1/workspaces

code

{
  "data": [
    {
      "id": "ws_aBcDeFgHiJkL",
      "name": "Main Marketing",
      "slug": "main-marketing",
      "role": "owner",
      "sites_count": 3,
      "members_count": 5,
      "plan": "professional",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Get Workspace

code

GET /v1/workspaces/{workspace_id}

Create Workspace

code

POST /v1/workspaces

Update Workspace

code

PATCH /v1/workspaces/{workspace_id}

Delete Workspace

code

DELETE /v1/workspaces/{workspace_id}

Warning: Deleting a workspace permanently removes all sites, data, and member access.

List Workspace Members

code

GET /v1/workspaces/{workspace_id}/members

Invite Member

code

POST /v1/workspaces/{workspace_id}/members

Update Member

code

PATCH /v1/workspaces/{workspace_id}/members/{member_id}

Remove Member

code

DELETE /v1/workspaces/{workspace_id}/members/{member_id}

Best Practices

Workspace Organization

| Scenario | Recommended Structure | |----------|----------------------| | Single business | 1 workspace, multiple sites | | Agency | 1 workspace per client | | Enterprise | 1 workspace per department/brand | | Freelancer | 1 workspace per project |

Naming Conventions

code

Workspace: [Company/Client] - [Project/Purpose]
  Examples:
  - "Acme Corp - Marketing"
  - "Client: TechStart - Main"
  - "Internal - Product Analytics"

Site: [Domain or App Name]
  Examples:
  - "acme.com"
  - "Acme Mobile App (iOS)"
  - "shop.acme.com"

View: [Filter Description]
  Examples:
  - "US Traffic Only"
  - "Paid Campaigns"
  - "Mobile App - Premium Users"

Security Recommendations

Principle of least privilege: Assign minimum necessary role
Regular access audits: Review member access quarterly
Separate test workspaces: Don't mix test and production data
Use SSO for enterprise: Enforce organization-wide authentication
Enable 2FA: Require two-factor for admin roles

Next: See Permissions to learn about fine-grained access control.

January 20268 min read

Workspaces

Organize your projects, sites, and team members with workspaces.

Overview

Workspaces are the top-level organizational unit in pxlpeak. They provide:

Isolation: Separate data, users, and billing between projects
Organization: Group related sites and team members
Access Control: Manage permissions at workspace and site levels
Billing: Independent subscription and usage tracking

code

┌─────────────────────────────────────────────────────────────────┐
│                        Organization                              │
│  (Your pxlpeak account)                                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │   Workspace A    │  │   Workspace B    │  │  Workspace C │  │
│  │   (Marketing)    │  │   (Client ABC)   │  │  (Personal)  │  │
│  ├──────────────────┤  ├──────────────────┤  ├──────────────┤  │
│  │ • Main Website   │  │ • abc.com        │  │ • blog.me    │  │
│  │ • Landing Pages  │  │ • shop.abc.com   │  │              │  │
│  │ • Mobile App     │  │ • app.abc.com    │  │              │  │
│  │                  │  │                  │  │              │  │
│  │ 5 team members   │  │ 3 team members   │  │ 1 member     │  │
│  │ Pro plan         │  │ Enterprise       │  │ Free plan    │  │
│  └──────────────────┘  └──────────────────┘  └──────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Creating a Workspace

Via Dashboard

Click Workspaces in the sidebar
Click Create Workspace
Enter workspace details:
- Name: Descriptive name (e.g., "Acme Corp Marketing")
- Slug: URL-friendly identifier (e.g., "acme-marketing")
- Timezone: Default timezone for reports
- Currency: Default currency for revenue

Via API

code

const response = await fetch('https://api.pxlpeak.com/v1/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Client Project',
    slug: 'client-project',
    timezone: 'America/New_York',
    currency: 'USD',
    settings: {
      data_retention_days: 730,
      ip_anonymization: true
    }
  })
});

const workspace = await response.json();
// { id: 'ws_xxx', name: 'Client Project', ... }

Workspace Structure

Sites

Sites are individual properties (websites, apps) within a workspace:

code

// Create a site in a workspace
const site = await pxlpeak.sites.create({
  workspaceId: 'ws_xxx',
  name: 'Main Website',
  domain: 'example.com',
  timezone: 'America/Los_Angeles', // Override workspace default
  settings: {
    tracking_enabled: true,
    cookie_consent_required: true,
    cross_domain_tracking: ['shop.example.com', 'blog.example.com']
  }
});

Site Hierarchy:

Views

Views provide filtered perspectives on site data:

code

// Create a filtered view
const view = await pxlpeak.views.create({
  siteId: 'site_xxx',
  name: 'US Mobile Traffic',
  filters: [
    { field: 'country', operator: 'eq', value: 'US' },
    { field: 'device_type', operator: 'eq', value: 'mobile' }
  ],
  permissions: {
    inherit_from_site: true
  }
});

Team Management

Inviting Members

code

// Invite a team member
await pxlpeak.workspaces.inviteMember({
  workspaceId: 'ws_xxx',
  email: 'colleague@example.com',
  role: 'editor',
  siteAccess: ['site_xxx', 'site_yyy'], // Or 'all' for full access
  message: 'Join our analytics workspace!'
});

Workspace Roles

Role Permissions Matrix

code

Permission                 │ Owner │ Admin │ Editor │ Analyst │ Viewer
───────────────────────────┼───────┼───────┼────────┼─────────┼───────
View analytics             │   ✓   │   ✓   │   ✓    │    ✓    │   ✓
Create reports             │   ✓   │   ✓   │   ✓    │    ✓    │
Export data                │   ✓   │   ✓   │   ✓    │    ✓    │
Create goals/segments      │   ✓   │   ✓   │   ✓    │         │
Manage sites               │   ✓   │   ✓   │        │         │
Manage members             │   ✓   │   ✓   │        │         │
Workspace settings         │   ✓   │   ✓   │        │         │
Billing & subscription     │   ✓   │       │        │         │
Delete workspace           │   ✓   │       │        │         │

Managing Member Access

code

// Update member role
await pxlpeak.workspaces.updateMember({
  workspaceId: 'ws_xxx',
  memberId: 'member_yyy',
  role: 'admin',
  siteAccess: 'all'
});

// Remove member
await pxlpeak.workspaces.removeMember({
  workspaceId: 'ws_xxx',
  memberId: 'member_yyy'
});

// List members
const members = await pxlpeak.workspaces.listMembers({
  workspaceId: 'ws_xxx'
});

Workspace Settings

General Settings

code

// Update workspace settings
await pxlpeak.workspaces.update({
  workspaceId: 'ws_xxx',
  settings: {
    // Display settings
    name: 'Updated Workspace Name',
    timezone: 'Europe/London',
    currency: 'GBP',
    date_format: 'DD/MM/YYYY',

    // Privacy settings
    ip_anonymization: true,
    data_retention_days: 365,

    // Feature flags
    features: {
      cross_domain_tracking: true,
      enhanced_attribution: true,
      predictive_analytics: false
    },

    // Notifications
    notifications: {
      weekly_digest: true,
      alert_emails: ['alerts@example.com'],
      slack_webhook: 'https://hooks.slack.com/...'
    }
  }
});

Data Retention

Configure how long data is retained:

code

// Update retention policy
await pxlpeak.workspaces.update({
  workspaceId: 'ws_xxx',
  settings: {
    data_retention_days: 365,
    retention_policy: {
      raw_events: 90,           // Detailed event data
      aggregated_data: 730,     // Daily/weekly summaries
      user_profiles: 365        // User identification data
    }
  }
});

Agency & Multi-Client Setup

White-Label Configuration

For agencies managing multiple client workspaces:

code

// Agency workspace with white-label settings
await pxlpeak.workspaces.update({
  workspaceId: 'ws_xxx',
  whiteLabel: {
    enabled: true,
    brandName: 'Agency Analytics',
    logoUrl: 'https://agency.com/logo.svg',
    primaryColor: '#4F46E5',
    customDomain: 'analytics.agency.com',
    removesBranding: true,
    customEmailDomain: 'analytics.agency.com'
  }
});

Client Workspace Structure

code

┌─────────────────────────────────────────────────────────────────┐
│                      Agency Organization                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    Agency Workspace                       │  │
│  │  (Internal use, all client access)                       │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │ • Agency Staff (Admin access to all)                     │  │
│  │ • Aggregated reporting                                   │  │
│  │ • Cross-client benchmarks                                │  │
│  └──────────────────────────────────────────────────────────┘  │
│                              │                                   │
│           ┌──────────────────┼──────────────────┐               │
│           ▼                  ▼                  ▼               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │  Client A    │  │  Client B    │  │  Client C    │         │
│  │  Workspace   │  │  Workspace   │  │  Workspace   │         │
│  ├──────────────┤  ├──────────────┤  ├──────────────┤         │
│  │ client-a.com │  │ client-b.com │  │ client-c.com │         │
│  │              │  │ shop-b.com   │  │              │         │
│  │              │  │              │  │              │         │
│  │ Client team: │  │ Client team: │  │ Client team: │         │
│  │ View only    │  │ View only    │  │ Analyst      │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Bulk Client Management

code

// Create client workspaces in bulk
async function createClientWorkspaces(clients: ClientInfo[]) {
  const results = [];

  for (const client of clients) {
    // Create workspace
    const workspace = await pxlpeak.workspaces.create({
      name: client.name,
      slug: client.slug,
      settings: {
        timezone: client.timezone,
        currency: client.currency
      }
    });

    // Create main site
    const site = await pxlpeak.sites.create({
      workspaceId: workspace.id,
      name: `${client.name} Website`,
      domain: client.domain
    });

    // Invite client team
    for (const contact of client.contacts) {
      await pxlpeak.workspaces.inviteMember({
        workspaceId: workspace.id,
        email: contact.email,
        role: 'viewer'
      });
    }

    // Add agency staff with admin access
    await pxlpeak.workspaces.inviteMember({
      workspaceId: workspace.id,
      email: 'team@agency.com',
      role: 'admin'
    });

    results.push({ workspace, site });
  }

  return results;
}

Cross-Workspace Features

Consolidated Reporting

View aggregated data across workspaces:

code

// Get cross-workspace summary
const summary = await pxlpeak.reports.crossWorkspace({
  workspaceIds: ['ws_xxx', 'ws_yyy', 'ws_zzz'],
  dateRange: {
    start: '2026-01-01',
    end: '2026-01-12'
  },
  metrics: ['sessions', 'conversions', 'revenue'],
  groupBy: 'workspace'
});

// Result:
// [
//   { workspace: 'Client A', sessions: 50000, conversions: 1200, revenue: 45000 },
//   { workspace: 'Client B', sessions: 30000, conversions: 800, revenue: 28000 },
//   { workspace: 'Client C', sessions: 20000, conversions: 500, revenue: 18000 }
// ]

Cross-Workspace Templates

Share configuration across workspaces:

code

// Create a template from existing workspace
const template = await pxlpeak.templates.create({
  sourceWorkspaceId: 'ws_xxx',
  name: 'E-commerce Standard',
  include: {
    goals: true,
    segments: true,
    dashboards: true,
    alerts: true
  }
});

// Apply template to new workspace
await pxlpeak.templates.apply({
  templateId: template.id,
  targetWorkspaceId: 'ws_new'
});

Workspace API Reference

List Workspaces

code

GET /v1/workspaces

code

{
  "data": [
    {
      "id": "ws_aBcDeFgHiJkL",
      "name": "Main Marketing",
      "slug": "main-marketing",
      "role": "owner",
      "sites_count": 3,
      "members_count": 5,
      "plan": "professional",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Get Workspace

code

GET /v1/workspaces/{workspace_id}

Create Workspace

code

POST /v1/workspaces

Update Workspace

code

PATCH /v1/workspaces/{workspace_id}

Delete Workspace

code

DELETE /v1/workspaces/{workspace_id}

Warning: Deleting a workspace permanently removes all sites, data, and member access.

List Workspace Members

code

GET /v1/workspaces/{workspace_id}/members

Invite Member

code

POST /v1/workspaces/{workspace_id}/members

Update Member

code

PATCH /v1/workspaces/{workspace_id}/members/{member_id}

Remove Member

code

DELETE /v1/workspaces/{workspace_id}/members/{member_id}

Best Practices

Workspace Organization

Naming Conventions

code

Workspace: [Company/Client] - [Project/Purpose]
  Examples:
  - "Acme Corp - Marketing"
  - "Client: TechStart - Main"
  - "Internal - Product Analytics"

Site: [Domain or App Name]
  Examples:
  - "acme.com"
  - "Acme Mobile App (iOS)"
  - "shop.acme.com"

View: [Filter Description]
  Examples:
  - "US Traffic Only"
  - "Paid Campaigns"
  - "Mobile App - Premium Users"

Security Recommendations

Principle of least privilege: Assign minimum necessary role
Regular access audits: Review member access quarterly
Separate test workspaces: Don't mix test and production data
Use SSO for enterprise: Enforce organization-wide authentication
Enable 2FA: Require two-factor for admin roles

Next: See Permissions to learn about fine-grained access control.