Skip to main content

Overview

useCreateWorkspaceInvite returns a callable that creates an invitation. Address the invitee by exactly one of email, userId, or username (here userId/username is the invite target, not the actor — the inviter is the signed-in user). Authorization: capability-gated + rank-bounded. Requires the invite capability (or ownership). The invited capabilities/permissions are subject to no-escalation, and if the inviter holds a direct member row the invited rank must be strictly larger (less senior) than their own. Rank comes in either coordinate. Pass relativeRank (an offset from the inviter — 1 = one rung below me) or rank (absolute), never both. Pass neither and the server applies relativeRank: 1, which is well defined for every inviter and can never fail the rank floor. See choosing a rank.
Your project must have workspaces.inviteAcceptUrl set before this hook can succeed. The invitation email deep-links to that URL, and it has no default — so a freshly added workspaces bundle has none and every call fails with 409 workspace/missing-invite-accept-url until you configure it. This holds even when the invitee already has an account. See Project settings.

Usage Example

Parameters

string
required
The workspace UUID.
string
Invitee email. One of email/userId/username. Trimmed + lowercased server-side, and matched case-insensitively against existing accounts — so an account stored as Jane@Example.com still gets its userId bound when invited as jane@example.com.
string
Invitee user id (existing users only) — the invite target.
string
Invitee username (existing users only).
WorkspaceCapability[]
Capabilities to apply on accept. Subject to no-escalation.
string[]
Opaque permissions to apply on accept.
number
Initial absolute rank. For a direct-member inviter it must be strictly larger (less senior) than their own; a reach-holder inviter (no direct row) may set any rank. No longer required — mutually exclusive with relativeRank, and omitting both applies the default below.
number
default:"1"
Initial rank as an offset from the inviter: 1 = one rung below me. Must be >= 1. Anchored on the inviter’s own rank if they hold a member row on this workspace, apex (one step above rank 0) otherwise. A snapshot — resolved to an absolute number at invite time and frozen; it does not track the inviter’s later rank changes.
string | null
Optional cosmetic title.

Returns

Returns the created WorkspaceInvitation object.

Error codes

Omitting the rank field is the easiest way to mint rank 0. The default is “one rung below me”, and a signed-in user with no member row on this workspace — the workspace’s owner, an ancestor owner, or a reach holder — anchors at apex, so their default lands on rank 0, the most senior rung. That is correct (one below apex is the top rung), but it is the opposite of what “I left the field off” usually implies. If a caller with no row here should be inviting people to the bottom of the ladder, name a coordinate instead.For an in-ladder inviter it collapses into a flat layer. A rank-0 lead inviting six people with no rank field gets six rank-1 members — and equals cannot act on equals, so none of them can manage each other; only the lead can. Fine for a flat team, worth deciding deliberately if your product has tiers.