---
title: "Invite a user by email"
method: POST
path: "/invitations"
---

# Invite a user by email

`POST /invitations`

## Request

- Base URL: `https://craaft.io/api/v1`
- URL: `https://craaft.io/api/v1/invitations`
- Auth: HTTP bearer

`boardGrants` is optional and only honoured for `role: "member"`
invitations - admin invitations auto-see every board. Grants are
persisted alongside the invitation and applied atomically when
the invitee accepts.

When the email already belongs to a verified account, the invite is
accepted on the spot and `consumed` is `true` (the person is now a
member). An unverified account leaves the invite pending until the
address is confirmed.

## Request body

- InvitationCreate
  - `email` string, email, required
  - `role` 'admin' | 'member', required
  - `boardGrants` object[]: Optional, only honoured for `role: "member"` invitations (admins auto-see every board). Persisted alongside the invitation and applied atomically on accept.
    - `projectId` string, uuid, required
    - `role` 'admin' | 'contributor', required

## Response `201`

Created. The invitation is wrapped, not returned bare.

- object
  - `invitation` Invitation, required
    - `id` string, uuid, required
    - `email` string, email, required
    - `role` 'admin' | 'member', required
    - `invitedBy` string, uuid, required
    - `invitedByName` string, required
    - `createdAt` string, date-time, required
    - `expiresAt` string, date-time, required
    - `boardGrants` InvitationGrant[], required
      - `projectId` string, uuid, required
      - `name` string, required
      - `role` 'admin' | 'contributor', required
  - `consumed` boolean, required: True when an existing verified account was added immediately

## Other responses

- `400`: Malformed body or invalid role
- `401`: Missing or invalid token
- `409`: Email already a member or has a pending invitation

---

[API](https://skmtc.dev/craaft/apis/craaft-api.md) · [All operations](https://skmtc.dev/craaft/apis/craaft-api/llms.txt) · [OpenAPI document](https://skmtc.dev/craaft/apis/craaft-api/revisions/3a1e9d30d7dc?raw)