API y SDK
Autenticación y claves de API
Cómo crear, usar y proteger las claves que autentican la API /v1.
Crear la clave en el panel
Sección titulada «Crear la clave en el panel»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.
Tipos de clave
Sección titulada «Tipos de clave»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.
La clave aparece una vez
Sección titulada «La clave aparece una vez»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.
Authorization: Bearer
Sección titulada «Authorization: Bearer»Envía la clave en el encabezado Authorization con el esquema Bearer, en cada solicitud:
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.
Errores de autenticación
Sección titulada «Errores de autenticación»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.
Probar en el /reference
Sección titulada «Probar en el /reference»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.
Rotar una clave
Sección titulada «Rotar una clave»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:
# crear la clave de una conexióncurl -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"]}'
# rotarcurl -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"}'
# revocarcurl -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.
Buenas prácticas
Sección titulada «Buenas prácticas»- 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.
X-Request-Id para soporte
Sección titulada «X-Request-Id para soporte»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.