Autenticación en el chat
Cómo se autentica tu aplicación en la API del chat con la cabecera X-Api-Key y qué más comprueba UTILIA OS antes de dejarla actuar.
Actualizado el . 2 min de lectura
Incluido en todos los planes. Ver precios
La API del chat se autentica con la clave de API de tu aplicación externa, en la cabecera X-Api-Key. Es el mismo mecanismo que el resto de la API REST, así que si ya usas otros endpoints no necesitas credenciales nuevas.
Si aún no tienes la aplicación ni su clave, créalas como se explica en Autenticación con clave de acceso.
La cabecera X-Api-Key
Cada petición lleva la clave, que empieza por utl_:
curl -X POST 'https://os.utilia.ai/api/external/v1/chat/channels/CHANNEL_ID/messages' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: utl_tu_clave_de_api' \
-d '{ "content": "Hola desde mi aplicación" }'La clave es secreta
La clave da a quien la tenga la identidad y los permisos de tu aplicación. Guárdala en tu servidor (variable de entorno o gestor de secretos) y no la pongas nunca en el código de una página web, de una aplicación móvil ni de un repositorio público.
Qué se comprueba en cada petición
Autenticarse es el primer paso, no el único. Con una clave válida, cada petición pasa además tres comprobaciones, en este orden:
Las comprobaciones de cada petición
Plan de tu organización
¿Está el Chat en el plan?
Lo comprueba el servidor en cada petición.Si no: 403 MODULE_NOT_ENABLED.
Ficha de la aplicación
¿Tiene el scope de la acción?
Por ejemplo, chat:messages:send para publicar.Si no: 403 INSUFFICIENT_SCOPE.
Si no: 403 al escribir, 404 al leer.
Al escribir sin concesión, el código es APP_NOT_AUTHORIZED_IN_CHANNEL; al leer, CHANNEL_NOT_FOUND. Los fallos de la propia clave (ausente, no válida o de una aplicación desactivada) son los mismos que en el resto de la API: los tienes en Errores, identificador de petición y reintentos.
El autor es siempre la aplicación
Lo que publica tu aplicación lo firma ella, nunca una persona. Por eso los cuerpos de las peticiones no aceptan campos de autoría ni de organización: la organización sale de la clave de API y el autor es tu aplicación. Así el registro de auditoría queda limpio y nadie puede hacerse pasar por un compañero.
Siguiente paso
Asigna a tu aplicación los scopes que vaya a usar y pide acceso a un canal, como se explica en Scopes y acceso por canal.