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

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

{
  "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 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.