Skip to main content

​
Workspaces API

While organizations represent standard B2B tenants, Wacht also supports a deeper layer of hierarchy called Workspaces. Workspaces typically exist within an Organization (e.g., an Organization is a “Company”, and Workspaces are “Projects” or “Departments”). 
import { WachtClient } from "@wacht/backend";

const client = new WachtClient({ apiKey: process.env.WACHT_API_KEY });

​
Reading Workspaces

​
listWorkspaces()

Retrieves a paginated list of all workspaces across your entire application. 
const response = await client.workspaces.listWorkspaces({ limit: 100 });
​
options
ListWorkspacesOptions

​
getWorkspace(workspaceId)

Retrieves a specific workspace by ID. 
const db = await client.workspaces.getWorkspace("ws_abc123");
​
workspaceId
string
required
The unique ID of the workspace you wish to resolve.

​
Mutating Workspaces

Note: The primary entry hook to create a workspace is normally executed via client.organizations.createWorkspaceForOrganization(), tying the workspace to a parent organization.

​
updateWorkspace(workspaceId, request)

Modify a workspace’s settings or metadata. 
const updated = await client.workspaces.updateWorkspace("ws_abc123", {
  name: "Project Phoenix - Q3",
  public_metadata: { status: "active" }
});
​
workspaceId
string
required
The ID of the target workspace.
​
request
UpdateWorkspaceRequest
required

​
deleteWorkspace(workspaceId)

Permanently destroy a workspace. 
await client.workspaces.deleteWorkspace("ws_abc123");
​
workspaceId
string
required
The target workspace ID.

​
Workspace Memberships

Just like Organizations, Workspaces have independent access control lists (ACLs) and Memberships.

​
listWorkspaceMembers(workspaceId)

Retrieve all users who have explicit access to this workspace. 
const members = await client.workspaces.listWorkspaceMembers("ws_abc123");
​
workspaceId
string
required
The target workspace ID.

​
addWorkspaceMember(workspaceId, request)

Grant a user access to the workspace. 
await client.workspaces.addWorkspaceMember("ws_abc123", {
  user_id: "usr_frontend_dev",
  role: "workspace:editor"
});
​
workspaceId
string
required
The ID of the workspace.
​
request
AddWorkspaceMemberRequest
required

​
updateWorkspaceMember(workspaceId, memberId, request)

Change a user’s role exclusively within the context of this workspace. 
await client.workspaces.updateWorkspaceMember("ws_abc123", "mem_456", {
  role: "workspace:viewer"
});
​
workspaceId
string
required
The ID of the workspace.
​
memberId
string
required
The target membership record ID.
​
request
UpdateWorkspaceMemberRequest
required

​
removeWorkspaceMember(workspaceId, memberId)

Revoke a user’s explicit access to the workspace. 
await client.workspaces.removeWorkspaceMember("ws_abc123", "mem_456");
​
workspaceId
string
required
The ID of the workspace.
​
memberId
string
required
The target membership record ID.

​
Custom Workspace Roles

Workspaces maintain their own discrete set of RBAC Roles and Permissions, isolated from organizational roles.
  • client.workspaces.listWorkspaceRoles(workspaceId)
  • client.workspaces.createWorkspaceRole(workspaceId, request)
  • client.workspaces.updateWorkspaceRole(workspaceId, roleId, request)
  • client.workspaces.deleteWorkspaceRole(workspaceId, roleId)