Miembros e invitaciones

Todas estas operaciones, incluida la lectura, requieren que el creador de la API key siga siendo administrador de la organización. REST exige Starter o Pro activo. La organización se determina por la clave.

Endpoints y permisos

Método y ruta	Scope	Parámetros	Éxito
`GET /api/v1/members`	`members:read`	Ninguno; sin paginación ni filtros	200 miembros e invitaciones pendientes
`POST /api/v1/invitations`	`members:write`	JSON `email` string obligatorio	201 invitación; envía correo
`PATCH /api/v1/members/:id`	`members:write`	ID de membresía positivo obligatorio; JSON `role` obligatorio	200 membresía actualizada
`DELETE /api/v1/members/:id`	`members:write`	ID de membresía positivo obligatorio, sin cuerpo	200 membresía retirada
`DELETE /api/v1/invitations/:id`	`members:write`	ID de invitación positivo obligatorio, sin cuerpo	200 invitación revocada

members:write incluye members:read. El ID de miembro es ID de membresía, no user_id. role solo puede ser admin o member. Invitar solo admite email, no role: se invita como miembro. No se aceptan attrs, IDs de organización, parámetros extra ni PUT. Los cuerpos de invite/role no admiten no-op vacío.

Listar

GET /api/v1/members
Authorization: Bearer <API_KEY>

Respuesta 200 de ejemplo:

{"data":{"members":[{"id":12,"user_id":8,"role":"admin"}],"invitations":[]}}

No hay meta. Una membresía tiene id, user_id enteros y role string; no incluye email o nombre del usuario. Una invitación tiene id, email, role, expires_at timestamp ISO 8601 y revoked_at timestamp ISO o null. No se expone token de aceptación.

Invitar, cambiar rol, retirar y revocar

POST /api/v1/invitations
Authorization: Bearer <API_KEY>
Content-Type: application/json

{"email":"persona\u0040example.org"}

201 {"data": invitación}. La persona debe aceptar el correo; crear una invitación no crea inmediatamente una membresía. No reintentes a ciegas tras un timeout: listar pendientes permite comprobar si se creó.

PATCH /api/v1/members/14
Authorization: Bearer <API_KEY>
Content-Type: application/json

{"role":"member"}

200 {"data":{"id":14,"user_id":9,"role":"member"}} como ejemplo. Cambiar a un rol ya asignado no implica crear otra membresía; siguen aplicándose las protecciones de administración.

DELETE /api/v1/members/14
Authorization: Bearer <API_KEY>

200 {"data": membresía} retirada; no elimina la cuenta personal del usuario ni devuelve 204.

DELETE /api/v1/invitations/20
Authorization: Bearer <API_KEY>

200 {"data": invitación} con revoked_at informado. Retirar una membresía no equivale a revocar una invitación.

Protecciones y errores

No puedes retirarte a ti mismo, cambiar tu propio rol ni dejar la organización sin administrador. Los scopes no eluden estas reglas. Una clave cuyo creador dejó de ser administrador pierde acceso a estas operaciones aunque conserve scopes.

HTTP / código	Causa
400 `invalid_params`	ID, email o role ausente/inválido; parámetros desconocidos
403 `forbidden`	Scope insuficiente o creador no administrador actual
404 `not_found`	Membresía/invitación inexistente o ajena
409 `conflict`	`cannot_remove_self`, `cannot_change_own_role`, `last_admin`, `already_member`, `invitation_already_pending`
422 `validation_error`	Email o datos de invitación inválidos
422 `operation_failed`	No se pudo completar la operación

Ejemplo: {"errors":{"code":"conflict","detail":"cannot_remove_self"}}. Se aplican también 401 y suscripción 403.

MCP

En Pro activo, una sola herramienta kordia_manage_members agrupa action: "list", "invite", "update_role", "remove", "revoke_invitation". Usa los campos correspondientes de la tabla (id, email, role), no todos a la vez. Solo list es lectura de negocio, aunque la herramienta agregada se anuncie como potencialmente destructiva y con efectos externos. Confirma la intención de invitar antes de enviar correo desde un agente.

Relacionado: organización, autenticación, conexión MCP.