Invitar a una persona a una organización

POST /v1/invitations · permiso invitations:write

Crea una invitación para que una dirección de correo electrónico se una a la organización. Sin organization_id, la invitación es de entorno: es el enlace de registro para el modo de registro solo por invitación, no abre ninguna pertenencia y no puede incluir roles (role_ids devuelve 422 validation_failed), y la respuesta tiene organization_id: null. delivery es obligatorio: email envía el correo de invitación con la plantilla de invitación del entorno (delivery_status: queued), el enlace solo aparece en el correo y la respuesta no tiene accept_url; link_only no envía ningún correo y devuelve el enlace para que lo comparta. El enlace de aceptación (accept_url) se devuelve únicamente en esta respuesta, una sola vez; ningún endpoint lo devuelve más tarde. La respuesta incluye Cache-Control: no-store, y una respuesta reproducida para el mismo Idempotency-Key omite el enlace e incluye secret_redacted: true. Si el envío de correos de invitación no está configurado para la implementación (solo en configuraciones que no son de producción), la entrega email devuelve 501 not_implemented y no se escribe nada. Si ya existe una invitación pendiente con los mismos roles para la organización y la dirección de correo electrónico, se reenvía con un nuevo enlace y la respuesta es 200. Una invitación pendiente que ha caducado pero aún no se ha procesado se marca como expired en la misma solicitud y se crea una nueva invitación (auditada como invitation.expired). Una invitación email pendiente con los mismos roles se reenvía por correo electrónico: la respuesta es 200 con delivery: email y sin accept_url. La escritura se audita como invitation.created.

Solicitud

Campo Tipo Requerido Descripción
organization_id string no ID de la organización (org_…); omítalo para una invitación de entorno (sin roles).
email string sí Dirección de correo electrónico de la persona invitada, de hasta 320 caracteres.
delivery string sí email (enlace solo en el correo electrónico) o link_only (enlace solo en esta respuesta).
role_ids string[] no Roles concedidos al aceptar (rol_…), como máximo 10; si está vacío, se usa el rol de miembro predeterminado.
application_id string no Aplicación en la que aterriza la persona invitada (app_…); debe existir en este entorno.
ttl_days integer no De 1 a 30; el valor predeterminado es invitation_ttl_days del entorno (7).

Respuesta

201 Created con la invitación y su enlace de aceptación (200 OK cuando se reenvió una invitación pendiente).

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

Errores

HTTP código Cuándo
404 not_found La organización o la aplicación no existe en este entorno.
409 invitation_already_pending Existe una invitación pendiente con roles distintos para esta dirección de correo electrónico.
409 membership_already_exists La dirección de correo electrónico ya pertenece a un miembro.
409 organization_disabled La organización está deshabilitada.
422 invitation_invalid La invitación no puede crearse con estos valores.
422 validation_failed Falta un campo o no es válido.
429 invite_rate_limited La invitación se reenvió hace menos de 10 minutos o ya se reenvió 5 veces.
501 not_implemented delivery es email y el envío de correos de invitación no está configurado para la implementación.
401 unauthenticated Falta la credencial, no es válida o ha sido revocada.
403 insufficient_permissions La credencial no tiene el permiso necesario. Asignar un rol privilegiado (is_privileged) también requiere roles:write; sin él no se escribe nada y required_permissions enumera ambos permisos.
429 rate_limited Se superó el límite de frecuencia; vuelva a intentarlo después del periodo indicado en Retry-After.
503 service_unavailable Una dependencia no está disponible temporalmente; vuelva a intentarlo después del periodo indicado en Retry-After.

Ejemplo

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

Datos personales

Este endpoint contiene datos personales: pertenencias a organizaciones e invitaciones. Datos personales en las API de KeenAuth describe qué se almacena, durante 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.