# 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](/docs/api/fapi/front-api-token)). 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

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

## Datos personales

Este endpoint contiene datos personales: membresías e invitaciones de organizaciones. [Datos personales en las API de KeenAuth](/docs/policies/personal-data) 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.