---
title: "Create invite"
method: POST
path: "/invite"
tags: ["Invites"]
---

# Create invite

`POST /invite`

## Request

- Base URL: `https://api.elaichi.ai`
- URL: `https://api.elaichi.ai/invite`
- Auth: HTTP bearer

Emails the invitee an accept link and returns the raw `token` once so an app can also show a copy-paste link — it is stored only as a hash and cannot be read back. Valid for seven days. An invite is a deferred role assignment, so the same no-escalation rule as `PATCH /member/{userId}` applies: you may only invite with roles whose permissions you already hold. Requires `member:manage`. Inviting someone who is already a member answers 409. A browser session must also pass a fresh step-up reauthentication in the app (without it the call answers `428 step_up_required`). An organization API token is not challenged.

## Headers

- `X-Organization-Id` string

## Request body

- object
  - `email` string, email, required: Lowercased before storage.
  - `role_ids` string[], required: Exactly one role (`role_…`), granted on acceptance.
  - `team_ids` string[]: Teams (`team_…`) to join. Defaults to none.

## Response `201`

Created

- object
  - `id` string: Invite id (`inv_…`).
  - `email` string, email: Lowercased at creation.
  - `role_ids` string[]: The single role (`role_…`) the invitee receives on acceptance.
  - `team_ids` string[]: Teams (`team_…`) they are added to.
  - `status` string: Lifecycle state; only `pending` invites can still be accepted.
  - `expires_at` string, date-time: Seven days after creation.
  - `invited_by` string, nullable: User id (`usr_…`) of the inviter.
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `token` string: Raw invite token — returned once, never retrievable again.
  - `email_sent` boolean: False when the invite email could not be delivered (the token still works).

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `429`: Rate limited

---

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