Workspace Guide

Overview

The SYSTEM workspace domain defines where a user can operate, which workspace is considered the default, and how members and roles are managed. In the published docs the workspace surface is split between /web/v1/tenant/workspaces/* for user-scoped actions and /web/v1/workspaces/* for some creation and admin-style operations.

What This Domain Covers

1. listing workspaces available to the current user
2. creating a workspace for the authenticated user
3. setting a default workspace
4. role discovery and role creation
5. invitation creation and member role assignment

Common Prerequisites

1. Authorization: Bearer <accessToken>
2. X-PORTAL-ACCESS-CODE: <system-portal-code>
3. the current user's account is active and allowed to access workspace data
4. secure-channel support for encrypted mutations when required by the gateway

Shared Headers

X-PORTAL-ACCESS-CODE: <system-portal-code>
Authorization: Bearer <accessToken>
Content-Type: application/json

Endpoint Families

User-scoped workspace endpoints

1. GET /web/v1/tenant/workspaces/mine
2. POST /web/v1/tenant/workspaces/{workspaceBizId}/default
3. POST /web/v1/tenant/workspaces/{workspaceBizId}/leave

Workspace management endpoints

1. POST /web/v1/workspaces/self
2. GET /web/v1/workspaces/{workspaceId}/roles
3. POST /web/v1/workspaces/{workspaceId}/roles
4. POST /web/v1/workspaces/{workspaceBizId}/invitations
5. POST /web/v1/workspaces/{workspaceId}/members/role/change

Typical Developer Sequence

1. load the user's accessible workspaces
2. create a workspace if none exist and the product supports self-service setup
3. set the preferred default workspace
4. list roles and create a custom role if member permissions need customization
5. invite collaborators and update their roles after they join

Decision Points

1. whether the user is allowed to self-create a workspace or must join through an invitation
2. whether the current role can manage invitations and role assignments
3. whether the app should always enter the default workspace or show a selector
4. whether a workspace uses only the built-in owner role or also custom roles

Error Handling

1. WORKSPACE.ALREADY_OWNS_WORKSPACE means the user can no longer self-create a second owned workspace
2. 4010 usually means a bad or expired JWT, not a broken workspace resource
3. WORKSPACE.ROLE_NAME_EXISTS means the caller should reuse or rename the role
4. invitation conflicts usually come from duplicate pending invites, not from email-delivery issues
5. remember that the user-scoped and admin-style workspace paths are both valid in SYSTEM; do not normalize them blindly to a single prefix

Related Domains

Workspace logic is tightly connected to:

1. Account Profile and Onboarding
2. Account Security and Invitations
3. Wallets Guide
4. Transfers Guide

Next Steps

1. Default Workspace and Membership
2. Account Guide
3. Wallets Guide