# Invita un membro

`POST /fapi/v1/organizations/{org_id}/invitations` · chiamato dall'host di accesso dell'ambiente

Invia un invito all'indirizzo email indicato per l'organizzazione. KeenAuth invia l'email di invito; il token di invito e il link di accettazione non ti vengono mai restituiti. Se per lo stesso indirizzo esiste già un invito in attesa con gli stessi ruoli, viene inviato di nuovo e la risposta è `200 OK`; un nuovo invito riceve `201 Created`.

Richiede il cookie `__Host-idp_session` dell'utente autenticato con un `Origin` esatto, oppure l'access token dell'API front di un'app first-party (`Authorization: DPoP <token>` con una prova DPoP; vedi [Access token dell'API front](/docs/api/fapi/front-api-token)). L'utente deve essere un membro attivo dell'organizzazione con l'autorizzazione `idp_members:invite`. Un utente che non è membro riceve `404 not_found`; un membro senza l'autorizzazione riceve `403 insufficient_permissions`. Solo un membro con il ruolo di amministratore può invitare con un ruolo privilegiato (`403 role_not_assignable`).

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

## Richiesta

Header:

| Header | Obbligatorio | Descrizione |
| --- | --- | --- |
| `Idp-Client` | sì | Identificativo dell'SDK. |
| `Origin` | sì, con il cookie | `https://<sign-in host>`. |

`org_id`: l'identificativo dell'organizzazione (`org_…`).

Corpo:

| Campo | Obbligatorio | Descrizione |
| --- | --- | --- |
| `email` | sì | L'indirizzo email da invitare, massimo 254 caratteri. |
| `role_ids` | no | Massimo 10 ruoli (`rol_…`); se assente, si usa il ruolo predefinito dell'organizzazione. |
| `ttl_days` | no | Per quanti giorni l'invito resta valido, da 1 a 30; se omesso, il valore predefinito dell'ambiente. |

## Risposta

`201 Created` con `Location` e `ETag`, oppure `200 OK` quando un invito in attesa è stato inviato di nuovo. Il corpo è l'invito:

`id` (`inv_…`), `email` (solo finché è in attesa, altrimenti `null`), `role_ids`, `delivery`, `delivery_status` (`queued`, `sent`, `bounced` o `not_sent`), `status` (`pending`, `accepted`, `revoked` o `expired`), `send_count`, `last_sent_at`, `expires_at`, `accepted_user_id`, `accepted_at`, `revoked_at`, `created_at`, `updated_at`, `version`.

## Errori

| Stato | Codice | Quando |
| --- | --- | --- |
| 400 | `unknown_field` | Il corpo contiene un campo non elencato sopra. |
| 401 | `unauthenticated` | Cookie di sessione o token assente o non valido. |
| 403 | `insufficient_permissions` | L'utente non ha `idp_members:invite` nell'organizzazione. |
| 403 | `role_not_assignable` | Un ruolo è privilegiato e l'utente non ha il ruolo di amministratore. |
| 403 | `origin_not_allowed` | `Origin` non corrisponde. |
| 404 | `not_found` | Nessuna organizzazione o ruolo del genere per questo utente. |
| 409 | `invitation_already_pending` | Esiste un invito in attesa per questo indirizzo con ruoli diversi. |
| 409 | `membership_already_exists` | L'indirizzo appartiene a un membro dell'organizzazione. |
| 409 | `organization_membership_limit_reached` | L'organizzazione ha raggiunto il limite di membri. |
| 409 | `organization_disabled` | L'organizzazione è disattivata o in attesa di cancellazione (`organization_pending_deletion`). |
| 422 | `validation_failed` | `email`, `role_ids` o `ttl_days` manca o non è valido. |
| 429 | `invite_rate_limited` | Troppi inviti o reinvii; riprova dopo `Retry-After`. |
| 501 | `not_implemented` | L'invio delle email di invito non è configurato in questo ambiente. |
| 503 | `service_unavailable` | Temporaneamente non disponibile; riprova dopo `Retry-After`. |

## Esempio

```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
}
```

## Dati personali

Questo endpoint tratta dati personali: appartenenze a organizzazioni e inviti. [Dati personali nelle API di KeenAuth](/docs/policies/personal-data) descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene cancellato. Non inviare categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale) in nessun campo.