Ir al contenido

API y SDK

Autenticación y claves de API

Cómo crear, usar y proteger las claves que autentican la API /v1.

En Claves de API → Crear clave, completa:

Campo Qué es
Nombre Hasta 32 caracteres, para reconocer la clave después (produccion, crm)
Permisos send (enviar mensajes), read (leer conexiones, conversaciones y logs), templates (crear y editar plantillas) y admin (todo). Marca solo lo que usa la integración
Conexiones Todas las conexiones o solo las seleccionadas. Una clave limitada a conexiones no ve las demás
Validez 30, 90, 180 o 365 días, o No vence
Límite por minuto De 1 a 6000 solicitudes por minuto (predeterminado: 600). Consulta Límites

Propietario, admin y dev crean claves. Solo propietario y admin otorgan el permiso admin. Una vez creada, la clave se puede editar (nombre, permisos, conexiones, límite), desactivar, reactivar o revocar.

Clave de organización (mj_) Clave de conexión (mjc_)
Dónde crearla Claves de API, a nivel de organización Pestaña Claves de API de la conexión
Alcance Cualquier conexión de la org; connection_id obligatorio en las rutas de mensajes Solo su conexión; connection_id es opcional (si se envía y es distinto, 403 connection_not_allowed)
Destinos Globales y de cualquier conexión Solo los de su conexión, nunca globales
Conexiones Listar, modificar y desconectar Leer y modificar la propia; no desconecta
Enlaces de conexión Sí 403 organization_key_required
Gestionar claves de conexión por /v1 Sí, con el permiso admin No
Eventos, entregas, logs y costos Toda la org Solo los de la conexión (más eventos de la WABA)
GET /v1/me api_key.kind = "org", connection_id y connection nulos api_key.kind = "connection", con connection_id y connection { id, channel, label }

Los permisos (send, read, templates, commerce, admin) valen para ambos tipos. Usa una clave de conexión por integración: solo ve su número y no necesita connection_id. Las claves de organización antiguas limitadas a varias conexiones siguen funcionando, pero el panel ya no ofrece esa opción.

Las plantillas, flows y catálogos pertenecen a la WABA: una clave de conexión que los modifica también afecta a las conexiones hermanas de la misma WABA.

El valor completo, que empieza con mj_ (organización) o mjc_ (conexión), solo aparece en el diálogo de creación. Messajo guarda solo un hash: ni el panel ni el soporte pueden mostrarla de nuevo. ¿La perdiste? Crea otra y revoca la anterior.

Para reconocer la clave después, el panel muestra el prefijo visible, sus primeros 10 caracteres (por ejemplo, mj_A1b2c3d). El mismo prefijo vuelve en el campo api_key.start de GET /v1/me.

Envía la clave en el encabezado Authorization con el esquema Bearer, en cada solicitud:

Ventana de terminal
curl https://api.messajo.com/v1/me \
-H "Authorization: Bearer $MESSAJO_API_KEY"

La cookie de sesión del panel nunca autentica la API /v1: una solicitud solo con cookie recibe missing_api_key. Tampoco se acepta la clave en la query string.

Todo error usa el cuerpo único de la API, con un code estable:

{
"error": {
"code": "missing_api_key",
"message": "Missing API key: send Authorization: Bearer <key>",
"meta_code": null,
"retryable": false,
"request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b",
"docs_url": "https://docs.messajo.com/errors#missing_api_key"
}
}
Estado code Cuándo
401 missing_api_key Falta el encabezado Authorization: Bearer
401 invalid_api_key La clave no existe o fue revocada
401 api_key_expired La clave venció
401 api_key_disabled La clave fue desactivada en el panel
403 insufficient_permissions La clave no tiene el permiso que exige la ruta
403 connection_not_allowed La clave está limitada a otras conexiones
403 organization_key_required La ruta es solo de clave de organización y la clave es de conexión

Ninguno de estos errores se resuelve repitiendo la llamada (retryable: false): corrige la clave o sus permisos.

La referencia interactiva está en https://api.messajo.com/reference. Allí pegas la clave en Authentication y usas Test request para llamar las rutas de verdad, como GET /v1/me.

La llamada sale de tu navegador hacia el propio servidor, en el mismo origen, sin pasar por proxies de terceros. La referencia de esta documentación es solo de lectura y no envía solicitudes.

En el panel, Rotar crea una clave nueva con el mismo nombre, tipo, permisos, conexión y límite, y muestra el valor nuevo una sola vez. La clave anterior sigue valiendo durante una gracia: 24 horas (predeterminado) o ahora, que la termina al instante. La gracia nunca supera la validez original. Una clave desactivada o vencida no se puede rotar.

Por /v1, una clave de organización con admin crea, rota y revoca solo claves de conexión (grace: 24h o now). Las claves de organización se rotan en el panel; /v1 devuelve 404 not_found para ellas:

Ventana de terminal
# crear la clave de una conexión
curl -X POST https://api.messajo.com/v1/connections/$CONNECTION_ID/api-keys \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "crm", "permissions": ["send", "read"]}'
# rotar
curl -X POST https://api.messajo.com/v1/api-keys/$KEY_ID/rotate \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"grace": "24h"}'
# revocar
curl -X DELETE https://api.messajo.com/v1/api-keys/$KEY_ID \
-H "Authorization: Bearer $MESSAJO_API_KEY"

La respuesta de la rotación trae el secreto nuevo y previous_key_expires_at, el fin de la gracia de la anterior. Los campos completos están en la referencia.

  • Variable de entorno o gestor de secretos, nunca en el código ni en el repositorio.
  • Nunca en el navegador ni en la app móvil. Cualquiera extrae una clave de un front-end. Llama a Messajo desde tu back-end.
  • Una clave por integración, con los permisos mínimos y, si se puede, limitada a las conexiones que usa. Si una se filtra, revocas solo esa.
  • Validez definida para claves de prueba y de terceros.
  • Rotar sin cortes: crea la clave nueva, cámbiala en la integración, revisa el último uso de la anterior en el panel y recién entonces revócala. El último uso se actualiza como máximo cada ~5 s por réplica y el contador de solicitudes no es exacto por llamada (la verificación de la clave se cachea 5 s).
  • ¿Se filtró? Revócala de inmediato. La siguiente llamada con ella ya recibe invalid_api_key.

Toda respuesta, de éxito o de error, trae el encabezado X-Request-Id (req_…). El mismo valor aparece en request_id en el cuerpo de los errores y de GET /v1/me.

Guarda ese valor en el log de tu integración. Al pedir ayuda, envía el X-Request-Id: con él, el soporte encuentra la llamada exacta sin que tengas que enviar la clave.