Skip to content

Workspaces & Roles

Learn how to organize users and permissions using workspaces and roles.

Workspaces

Workspaces provide data isolation within a tenant.

When to Use Workspaces

  • Multi-team SaaS: Each customer team gets a workspace
  • Project-based: Each project is a workspace
  • Department separation: HR, Engineering, Sales
  • Client portals: Each client has a workspace

Creating Workspaces

curl -X POST http://localhost:8000/api/sso/v1/workspaces \
  -H "Authorization: Bearer TOKEN" \
  -d '{"name": "Engineering", "slug": "engineering"}'

Workspace Members

Users can belong to multiple workspaces with different roles in each:

{
  "user_id": "user:alice",
  "workspaces": [
    {"workspace_id": "ws_eng", "roles": ["developer"]},
    {"workspace_id": "ws_design", "roles": ["viewer"]}
  ]
}

Roles

Roles are permission bundles assigned to users.

Built-in Role Patterns

Role Typical Scopes Use Case
Admin *:* Full access
Editor read:*, write:* Create/edit content
Viewer read:* Read-only access
Support read:users, impersonate:users Customer support

Creating Roles

curl -X POST http://localhost:8000/api/sso/v1/roles \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "name": "Developer",
    "slug": "developer",
    "scopes": ["read:code", "write:code", "deploy:staging"]
  }'

Assigning Roles

curl -X PATCH http://localhost:8000/api/sso/v1/users/USER_ID \
  -H "Authorization: Bearer TOKEN" \
  -d '{"roles": ["developer", "viewer"]}'

Scopes

Scopes are granular permissions. Recommended naming:

  • action:resource - e.g., read:posts, write:users
  • action:resource:field - e.g., read:users:email
  • action:* - Wildcard, e.g., read:*

Common Scopes

scopes = [
    # Read operations
    "read:users",
    "read:posts",
    "read:analytics",

    # Write operations
    "write:posts",
    "write:comments",

    # Delete operations
    "delete:posts",

    # Admin operations
    "admin:workspace",
    "admin:users"
]

Best Practices

1. Workspace Strategy

Choose based on your use case:

Option A: Per-Customer 

Tenant: YourApp
├── Workspace: Customer A
├── Workspace: Customer B
└── Workspace: Customer C

Option B: Per-Team 

Tenant: Company
├── Workspace: Engineering
├── Workspace: Marketing
└── Workspace: Sales

2. Role Hierarchy

Create logical hierarchies:

admin (all scopes)
  ↓
manager (read:*, write:*, some admin)
  ↓
editor (read:*, write:own)
  ↓
viewer (read:*)

3. Scope Naming

Be consistent:

# ✅ Good
"read:users"
"write:posts"
"delete:comments"

# ❌ Bad
"users_read"
"create_post"
"remove_comment"