Create Invite
Workspace — Invitations
Create Invite
Invite a user by email, userId, or username
Create Invite
Creates an invitation, addressed by exactly one of
A project misconfiguration, not a bad request — the payload is fine and the caller is authorized. Set
See also: useCreateWorkspaceInvite · createWorkspaceInvite (js-sdk) · createWorkspaceInvite (node-sdk)
email, userId, or username. Requires the invite capability. Always sends an email (no toggle). Fires workspace.invite.created.
The invited capabilities/permissions are validated against the inviter’s own resolved set on the workspace — no-escalation on both arrays. The rank floor applies only when the inviter has a direct member row on the workspace: then the invited rank must be strictly larger (less senior) than the inviter’s own. A reach-holder inviter (holding invite via an open inherit chain, with no direct row) is not in the workspace’s rank ladder and may invite at any rank.
Duplicate handling:
- Inviting an existing member →
409(change the grant via Update Member). - A live invite (
pendingand not pastexpiresAt) for the same target → idempotent refresh (updates the grant, resets a 14-day expiry). - A terminal (
accepted/declined/revoked) or effectively-expired invite does not block — a freshpendingis created. (Anacceptedinvite means the user is already a member, so re-inviting them returns409instead.)
userId at creation. The account lookup is case-insensitive, so an account stored as Jane@Example.com is still bound when invited as jane@example.com.
Path Parameters
string
required
The workspace UUID.
Body Parameters
string
Invitee email (trimmed + lowercased server-side). One of
email/userId/username is required. Matching an existing account is case-insensitive, so an address that was stored with different capitalization (as OAuth-created accounts are) still binds its userId.string
Invitee user id (existing users only). Here
userId is the invite target, not an acting user.string
Invitee username (existing users only).
string[]
Capabilities to apply on accept. Defaults to
[]. Subject to no-escalation.string[]
Opaque permissions to apply on accept. Defaults to
[]. Subject to no-escalation.number
required
Initial rank to apply on accept. 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.
string
Optional initial cosmetic title.
Response
Returns the created WorkspaceInvitation object.Error Responses
Already a Member — 409
Already a Member — 409
No Escalation — 403
No Escalation — 403
Missing Invite Accept URL — 409
Missing Invite Accept URL — 409
workspaces.inviteAcceptUrl in your project settings and retry the identical request.
