Create Workspace
Workspace Endpoints
Create Workspace
Create a root or child workspace
Create Workspace
Creates a workspace. The authenticated caller becomes the
Also returned when a service or master key creates a root workspace on behalf of an unverified
See also: useCreateWorkspace · createWorkspace (node-sdk)
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 nameduserIdstill 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-workspacecapability 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
Email Not Verified — 403
Email Not Verified — 403
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.Parent Not Found — 404
Parent Not Found — 404
Max Depth Exceeded — 400
Max Depth Exceeded — 400

