API de administración

El motor tiene dos APIs con dos identidades que no se mezclan:

	`/v1`	`/admin/api`
Para quién	Las apps cliente: tu CRM, tus conectores.	Los operadores del motor, a través del panel.
Credencial	`Authorization: Bearer mw_…` (una API key con scopes).	La cookie de sesión `mw_sesion` y el encabezado `X-CSRF-Token`.
Alcance	Solo lo de tu app, filtrado por la key.	Todo el motor: todas las apps, todas las instancias, los Ajustes.
Contrato	Estable y versionado: la Referencia de /v1.	Interno: cambia con el panel.

Una API key no sirve en /admin/api y una sesión de operador no sirve en /v1: las dos responden 401.

Qué hace

A grandes rasgos, lo que un operador hace desde el panel:

Apps cliente y keys: crear, suspender y reactivar apps; su cupo de instancias y sus destinos permitidos; emitir, rotar y revocar API keys.
Instancias: crearlas para una app, vincularlas, reconectar, pausar, desvincular, archivar, su diagnóstico y sus métricas, y las mismas operaciones de mensajería que tiene /v1, para probar desde el panel.
Eventos: el inspector técnico del ledger (sin payloads), las suscripciones de webhooks de cada app, las entregas y el replay, los streams abiertos (y cortarlos) y los bridges a NATS, RabbitMQ, Kafka y SQS.
El motor: los Ajustes, la auditoría, el estado (base, migraciones, versión de whatsmeow), la operación y el watchdog, los backups y los proxies.

La sesión

Los operadores son cuentas del motor. No hay alta por la API: se crean con motorctl en la máquina del motor, con la contraseña por la entrada estándar (nunca en un argumento):

motorctl operador crear --email operador@ejemplo.com --nombre "Operador" --rol superadmin

Ruta	Qué hace
`POST /admin/api/sesion`	Entra con `{ email, password }`. Responde `{ operador, csrf }` y fija dos cookies.
`GET /admin/api/sesion`	El operador de la sesión y su `csrf`.
`DELETE /admin/api/sesion`	Sale y borra las cookies.

mw_sesion: la sesión. HttpOnly, SameSite=Strict y, en producción, Secure. Dura 12 h por omisión (Ajustes: seguridad.sesion_horas, de 1 a 168); al vencer, el operador vuelve a entrar.
Intentos: 5 fallidos cada 15 minutos, contados por correo y por IP (Ajustes: seguridad.intentos_login). Al pasarlos, 429 con Retry-After.
motorctl operador revocar-sesiones --email … cierra todas las sesiones de un operador.

El CSRF

El CSRF es de doble envío: al entrar, el motor fija también la cookie mw_csrf (legible desde la página) y devuelve el mismo valor en csrf. Toda mutación con sesión (POST, PUT, PATCH, DELETE) manda ese valor en el encabezado X-CSRF-Token. Sin él, o con uno que no corresponde a la sesión, la respuesta es 403. El login no lo pide.

Los roles

Rol	Qué puede
`operador`	Ver todo y operar las instancias del día a día: crearlas, vincularlas, reconectar, pausar, probar envíos, revisar entregas, la DLQ de un bridge y los diagnósticos.
`superadmin`	Todo lo anterior, más lo que administra credenciales y políticas: crear, cambiar, suspender y reactivar apps; sus destinos permitidos; emitir, rotar y revocar keys; los Ajustes; desvincular o archivar una instancia; crear, cambiar, borrar y reenviar suscripciones y bridges; los backups y los proxies; exportar la configuración.

El rol se exige en el servidor: un operador que intenta algo de superadmin recibe 403 («Tu rol de operador no permite esta acción: pídesela a un superadmin.»), aunque el panel ya oculte el botón.

La referencia

La referencia de /admin/api no se publica en este sitio ni en el motor: la Referencia de /v1 y su openapi-v1.json están filtrados a /v1 a propósito, y el propio motor sirve en GET /openapi.json y en /docs solo el contrato público (/v1 y los eventos). Si operas el motor y necesitas el detalle, está en su repositorio:

docs/api-admin.md describe cada ruta de administración, sus entradas y sus salidas.
docs/openapi.json es el contrato completo, con /v1 y /admin/api (se regenera con make openapi). Las rutas que solo puede usar un superadmin dicen «Solo superadmin.».

Los errores siguen el mismo formato que los de /v1: ver Errores.