# Invite a person to an organization

`POST /v1/invitations` · permission `invitations:write`

Creates an invitation for an e-mail address to join the organization. Without `organization_id` the invitation is an environment invitation: it is the sign-up link for the invite-only sign-up mode, opens no membership and cannot carry roles (`role_ids` returns `422 validation_failed`), and the response has `organization_id: null`. `delivery` is required: `email` sends the invitation e-mail with the environment's invitation template (`delivery_status: queued`), the link is only in the e-mail and the response has no `accept_url`; `link_only` sends no e-mail and returns the link for you to share. The accept link (`accept_url`) is returned only in this response, once; no endpoint returns it later. The response carries `Cache-Control: no-store`, and a response replayed for the same `Idempotency-Key` omits the link and carries `secret_redacted: true`. If invitation e-mail is not configured for the deployment (non-production setups only), `email` delivery returns `501 not_implemented` and nothing is written. If a pending invitation with the same roles already exists for the organization and e-mail, it is resent with a new link and the response is `200`. A pending invitation that has expired but not yet been processed is marked `expired` in the same request and a new invitation is written (audited as `invitation.expired`). A pending `email` invitation with the same roles is resent by e-mail: the response is `200` with `delivery: email` and no `accept_url`. The write is audited as `invitation.created`.

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `organization_id` | string | no | Organization ID (`org_…`); omit it for an environment invitation (no roles). |
| `email` | string | yes | E-mail address of the invitee, up to 320 characters. |
| `delivery` | string | yes | `email` (link only in the e-mail) or `link_only` (link only in this response). |
| `role_ids` | string[] | no | Roles granted on acceptance (`rol_…`), at most 10; default member role when empty. |
| `application_id` | string | no | Application the invitee lands in (`app_…`); it must exist in this environment. |
| `ttl_days` | integer | no | 1–30; default is the environment's `invitation_ttl_days` (7). |

## Response

`201 Created` with the invitation and its accept link (`200 OK` when a pending invitation was resent).

```json
{
  "id": "inv_01j9xt9v3w4y8z0a2b4c6d8e0g",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "email": "ada@example.com",
  "role_ids": [
    "rol_01j9xr7s1t2w6x8y0z2a4b6c8e"
  ],
  "application_id": null,
  "delivery": "link_only",
  "delivery_status": "not_sent",
  "status": "pending",
  "send_count": 1,
  "last_sent_at": "2026-10-12T09:31:00.123456Z",
  "expires_at": "2026-10-19T09:31:00.123456Z",
  "accepted_user_id": null,
  "accepted_at": null,
  "revoked_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z",
  "updated_at": "2026-10-12T09:31:00.123456Z",
  "version": 1,
  "accept_url": "https://acme.eu.keenauth.app/u/login?invitation=<token>"
}
```

## Errors

| HTTP | code | When |
|---|---|---|
| 404 | `not_found` | The organization or the application does not exist in this environment. |
| 409 | `invitation_already_pending` | A pending invitation with different roles exists for this e-mail. |
| 409 | `membership_already_exists` | The e-mail already belongs to a member. |
| 409 | `organization_disabled` | The organization is disabled. |
| 422 | `invitation_invalid` | The invitation cannot be created with these values. |
| 422 | `validation_failed` | A field is missing or invalid. |
| 429 | `invite_rate_limited` | The invitation was resent less than 10 minutes ago or 5 times already. |
| 501 | `not_implemented` | `delivery` is `email` and invitation e-mail is not configured for the deployment. |
| 401 | `unauthenticated` | The credential is missing, invalid or revoked. |
| 403 | `insufficient_permissions` | The credential lacks the required permission. Assigning a privileged (`is_privileged`) role also requires `roles:write`; without it nothing is written and `required_permissions` lists both permissions. |
| 429 | `rate_limited` | The rate limit was exceeded; retry after the `Retry-After` period. |
| 503 | `service_unavailable` | A dependency is temporarily unavailable; retry after the `Retry-After` period. |

## Example

```bash
curl -i -X POST "https://api.eu.keenauth.com/v1/invitations" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","email":"ada@example.com","delivery":"link_only","role_ids":["rol_01j9xr7s1t2w6x8y0z2a4b6c8e"]}'
```

## Personal data

This endpoint carries personal data: organization memberships and invitations. [Personal data in the KeenAuth APIs](/docs/policies/personal-data) describes what is stored, how long it is kept and how it is deleted. Do not send special categories of personal data (health, biometric data, religion, political opinions, sexual orientation) in any field.