E020: Send invitation

POST /api/organizations/current/invitations

Creates a tokenized invitation for a prospective member and emails them the accept link. Triggered from Settings, Users, Invite. Idempotent on repeat invites to the same pending email.

Authentication

Standard tenant route. Requires Authorization: Bearer <firebase-id-token> and X-Org-Id: <org-id>. Access: Admin.

Request

{
  "email": "newuser@example.com",
  "role": "member"
}

Field	Type	Required	Notes
email	string	yes	Lowercased server-side.
role	"admin" | "member"	yes	owner is rejected.

Response — 201 Created

{
  "invitation": {
    "id": "uuid",
    "orgId": "uuid",
    "email": "newuser@example.com",
    "role": "member",
    "token": "opaque-string",
    "expiresAt": "2026-05-25T22:00:00Z",
    "status": "pending"
  },
  "emailSent": true
}

Re-inviting an already-pending email returns the existing invitation row (idempotent) with emailSent: true after re-sending.

Errors

HTTP	code	Condition
422	validation_failed	Email belongs to an existing member, or role is owner.
403	forbidden	Caller is not owner/admin.

Workflow

Calls W020 Send invitation.