Invitar a un miembro

POST /fapi/v1/organizations/{org_id}/invitations · llamado desde el host de inicio de sesión del entorno

Invita a una dirección de correo electrónico a la organización. KeenAuth envía el correo de invitación; el token de invitación y el enlace de aceptación nunca se devuelven a usted. Si ya existe una invitación pendiente para la misma dirección con los mismos roles, se vuelve a enviar y la respuesta es 200 OK; una invitación nueva es 201 Created.

Requiere la cookie __Host-idp_session del usuario autenticado con un Origin exacto, o el token de acceso de la API frontal de una aplicación de primera parte (Authorization: DPoP <token> con una prueba DPoP; consulte Token de acceso de la API frontal). El usuario debe ser miembro activo de la organización con el permiso idp_members:invite. Un usuario que no es miembro recibe 404 not_found; un miembro sin el permiso recibe 403 insufficient_permissions. Solo un miembro con el rol de administrador puede invitar con un rol privilegiado (403 role_not_assignable).

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

Solicitud

Encabezados:

Encabezado Obligatorio Descripción
Idp-Client sí Identificador del SDK.
Origin sí, con la cookie https://<host de inicio de sesión>.

org_id: el identificador de la organización (org_…).

Cuerpo:

Campo Obligatorio Descripción
email sí La dirección que se invita, de como máximo 254 caracteres.
role_ids no Como máximo 10 roles (rol_…); si no se indica ninguno, se usa el rol predeterminado de la organización.
ttl_days no Durante cuántos días sigue válida la invitación, de 1 a 30 días; si se omite, se usa el valor predeterminado del entorno.

Respuesta

201 Created con Location y ETag, o 200 OK cuando se volvió a enviar una invitación pendiente. El cuerpo es la invitación:

id (inv_…), email (solo mientras está pendiente; si no, 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.

Errores

Estado Código Cuándo
400 unknown_field El cuerpo contiene un campo no listado arriba.
401 unauthenticated No hay una cookie de sesión o un token válido.
403 insufficient_permissions El usuario no tiene idp_members:invite en la organización.
403 role_not_assignable Un rol es privilegiado y el usuario no tiene el rol de administrador.
403 origin_not_allowed Origin no coincide.
404 not_found No existe tal organización o rol para este usuario.
409 invitation_already_pending Ya hay una invitación pendiente para esta dirección con roles distintos.
409 membership_already_exists La dirección pertenece a un miembro de la organización.
409 organization_membership_limit_reached La organización ha alcanzado su límite de miembros.
409 organization_disabled La organización está desactivada o pendiente de eliminación (organization_pending_deletion).
422 validation_failed Falta email, role_ids o ttl_days, o alguno no es válido.
429 invite_rate_limited Demasiadas invitaciones o reenvíos; reintente después de Retry-After.
501 not_implemented El envío de correos de invitación no está configurado en este entorno.
503 service_unavailable No disponible temporalmente; reintente después de Retry-After.

Ejemplo

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
}

Datos personales

Este endpoint contiene datos personales: membresías e invitaciones de organizaciones. Datos personales en las API de KeenAuth describe qué se almacena, cuánto tiempo se conserva y cómo se elimina. No envíe categorías especiales de datos personales (salud, datos biométricos, religión, opiniones políticas, orientación sexual) en ningún campo.