# Invite a member

`POST /fapi/v1/organizations/{org_id}/invitations` · called from the environment's sign-in host

Invites an e-mail address to the organization. KeenAuth sends the invitation e-mail; the invitation token and accept link are never returned to you. If a pending invitation already exists for the same address with the same roles, it is sent again and the answer is `200 OK`; a new invitation is `201 Created`.

Requires the authenticated user's `__Host-idp_session` cookie with an exact `Origin`, or a first-party app's front API access token (`Authorization: DPoP <token>` with a DPoP proof; see [Front API access token](/docs/api/fapi/front-api-token)). The user must be an active member of the organization with the `idp_members:invite` permission. A user who is not a member gets `404 not_found`; a member without the permission gets `403 insufficient_permissions`. Only a member who holds the admin role can invite with a privileged role (`403 role_not_assignable`).

With `@keenauth/js`: `const { invitation, resent } = await keenauth.organizations.invite(orgId, { email, roleIds: [roleId] })`.

## Request

Headers:

| Header | Required | Description |
| --- | --- | --- |
| `Idp-Client` | yes | SDK identifier. |
| `Origin` | yes, with the cookie | `https://<sign-in host>`. |

`org_id`: the organization identifier (`org_…`).

Body:

| Field | Required | Description |
| --- | --- | --- |
| `email` | yes | The address to invite, at most 254 characters. |
| `role_ids` | no | At most 10 roles (`rol_…`); none means the organization's default role. |
| `ttl_days` | no | How long the invitation stays valid, 1–30 days; the environment's default when omitted. |

## Response

`201 Created` with `Location` and `ETag`, or `200 OK` when a pending invitation was sent again. The body is the invitation:

`id` (`inv_…`), `email` (only while pending, else `null`), `role_ids`, `delivery`, `delivery_status` (`queued`, `sent`, `bounced` or `not_sent`), `status` (`pending`, `accepted`, `revoked` or `expired`), `send_count`, `last_sent_at`, `expires_at`, `accepted_user_id`, `accepted_at`, `revoked_at`, `created_at`, `updated_at`, `version`.

## Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `unknown_field` | The body has a field not listed above. |
| 401 | `unauthenticated` | No valid session cookie or token. |
| 403 | `insufficient_permissions` | The user lacks `idp_members:invite` in the organization. |
| 403 | `role_not_assignable` | A role is privileged and the user does not hold the admin role. |
| 403 | `origin_not_allowed` | The `Origin` does not match. |
| 404 | `not_found` | No such organization or role for this user. |
| 409 | `invitation_already_pending` | A pending invitation for this address has different roles. |
| 409 | `membership_already_exists` | The address belongs to a member of the organization. |
| 409 | `organization_membership_limit_reached` | The organization has reached its member limit. |
| 409 | `organization_disabled` | The organization is disabled or pending deletion (`organization_pending_deletion`). |
| 422 | `validation_failed` | `email`, `role_ids` or `ttl_days` is missing or invalid. |
| 429 | `invite_rate_limited` | Too many invitations or resends; retry after `Retry-After`. |
| 501 | `not_implemented` | Invitation e-mail is not set up in this environment. |
| 503 | `service_unavailable` | Temporarily unavailable; retry after `Retry-After`. |

## Example

```bash
curl -X POST "https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/invitations" \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"email":"new.member@example.com","role_ids":["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"],"ttl_days":7}'
```

```json
{
  "id": "inv_01jbz6x8kq3m2n4p5r6s7t8v9d",
  "email": "new.member@example.com",
  "role_ids": ["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"],
  "delivery": "email",
  "delivery_status": "queued",
  "status": "pending",
  "send_count": 1,
  "last_sent_at": "2026-11-03T10:00:00Z",
  "expires_at": "2026-11-10T10:00:00Z",
  "accepted_user_id": null,
  "accepted_at": null,
  "revoked_at": null,
  "created_at": "2026-11-03T10:00:00Z",
  "updated_at": "2026-11-03T10:00:00Z",
  "version": 1
}
```

## 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.