Invite someone to the Workspace

POST/api/v1/workspaces/{workspace_id}/invitations

Creates an invitation and returns the plain token once. Only a hash is stored, so the token cannot be recovered later and a database disclosure is not replayable into Workspace access. Repeating the request with the same Idempotency-Key replays the original response, token included, which is how a client that lost the first response recovers it.

role may be admin, member, or viewer — not owner. Ownership carries the archive power and the last-owner invariant, and is conferred by a deliberate membership change on somebody already present rather than by whoever opens a link in a mailbox.

A second unexpired pending invitation for the same address is refused 409 invitation_pending rather than silently reissued, so the link the recipient already received stays the live one. An address that already belongs to an active member is refused 409 already_member, which discloses nothing an administrator cannot read from the member list. If the configured email provider cannot accept the invitation, the transaction rolls back and the endpoint returns retryable 503 delivery_unavailable.

Path Parameters

workspace_idRequired

string <uuid>

Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-CSRF-TokenRequired

string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Idempotency-KeyRequired

string·min 16·max 200

Opaque client-generated key for safely retrying this operation.

Request Body

application/json

emailRequired

string <email>

roleRequired

string

owner is deliberately not invitable. Ownership carries the archive power and the last-owner invariant, and is conferred by a membership change on somebody already present.

Values

adminmemberviewer

Responses

Authentication · Conventions and errors · API guides · Resource reference

Invite someone to the Workspace