Workspaces

A workspace is an access context within an environment. Users join workspaces through memberships, and every permission check in Userbox is workspace-scoped. The same user can have different permissions in different workspaces.

A workspace is not a sub-account. It does not have its own API keys or isolated data store. It is a boundary for permission assignment within your tenant.

Two workspace patterns

Most applications fall into one of two patterns.

Pattern A — One workspace per organizational unit

Use one workspace to represent each organizational boundary in your application — typically one per customer organization in a B2B SaaS. Users from one customer organization cannot see or access resources from another because they are not members of that workspace.

Best for: B2B SaaS where each customer is an independent organization with its own team and access rules.

Pattern B — One workspace per application instance or tier

Use one workspace to represent each deployment or isolation boundary — for example, a production instance and a sandbox instance of your application. Users have different permission levels in each.

Best for: Applications where users need different access in isolated copies of the same product (e.g., production vs. sandbox, or per-region deployments).

Choosing a pattern

Scenario	Recommended pattern
B2B SaaS — customers are separate organizations	Pattern A (one workspace per customer)
Production and sandbox isolation within a single product	Pattern B (one workspace per tier)
Single-tenant app where all users have the same permissions	Single workspace
Teams within a product with different permissions	Pattern A (one workspace per team)

Concrete example: Health Startup

A health startup building three distinct platforms:

• Health Monitoring Platform — clinicians and patients track health data
• Internal Finance System — the startup's own finance team manages payroll and invoices
• Personal Trainer Platform — trainers and clients manage workout plans

Each platform becomes a workspace. A clinician has permissions in the Health Monitoring workspace but zero access to Internal Finance. A finance analyst is a member of Internal Finance only. A trainer belongs only to the Personal Trainer workspace.

This design means permission checks are simple, membership is explicit, and there is no cross-contamination between platforms.

What's next

• Platform permissions — Console and management access
• App permissions — Custom permissions you define for your application