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.
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
Related
useFetchWorkspaceInvites— the invites this workspace has issueduseRevokeWorkspaceInvite·useResendWorkspaceInvite- Project settings — the required
workspaces.inviteAcceptUrl - Create Invite API

