Skip to main content
Create Workspace
Creates a workspace. The authenticated caller becomes the ownerId. Omit parentWorkspaceId to create a root workspace; pass it to create a child.
  • Root creation requires the creator to have a verified email (else 403 workspace/email-not-verified). This is not a key-bypass gate: a service or master key acting as a named userId still requires that user to be verified. On a purely external-auth project this makes root creation unavailable — see the external-auth limitation.
  • Child creation requires the create-sub-workspace capability on the parent (held directly or via reach). The creator becomes the child’s owner. No separate verified-email gate (the capability-holder is already a verified member up-tree).
inheritsFromParent is never accepted from client input — it is server-set from the project default at creation, and cannot be overridden when the project’s default is enforced. depth is likewise server-computed.

Body Parameters

string
required
Display name for the workspace. 1–100 characters.
object
Optional arbitrary developer-defined data (opaque JSON). Defaults to {}.
string
Optional UUID of a parent workspace. Absent → root workspace. Requires the create-sub-workspace capability on the parent.
string
Service/master keys only — the user to act as (the created workspace’s owner). A plain user token may only act as itself and this field is ignored. The named user must satisfy the same gates a self-driven call would: for a root workspace they must have a verified email.

Response

Returns the created Workspace object.

Error Responses

Also returned when a service or master key creates a root workspace on behalf of an unverified userId — keys do not bypass this gate. Ownership has exactly three doors (create, accept an invite, receive a transfer) and all three enforce it identically, which is what guarantees every workspace participant has a confirmed email.
See also: useCreateWorkspace · createWorkspace (node-sdk)