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 actingUserId 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
required
Service/master keys only — the user to act as (the created workspace’s owner). Required for a key: this route has no unbounded path, so a key that names nobody is refused with 400 workspace/missing-user-id. The named user must satisfy the same gates a self-driven call would: for a root workspace they must have a verified email.A plain user token omits it — the actor is the token’s own user. The field is not ignored for such a token: sending your own user id is a harmless no-op, but sending anyone else’s is a 403 workspace/unauthorized. See Acting on behalf of a user.

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 actingUserId — 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.
A service/master key called this route without naming an actingUserId. There is no unbounded path here — a workspace has to be created by somebody, so the key must name that user.
A plain user token sent an actingUserId naming a different user. Only a service/master key may act as someone else.
See also: useCreateWorkspace · createWorkspace (node-sdk)