# 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.

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](https://os.utilia.ai/docs/developers/getting-started/authentication).

## La cabecera `X-Api-Key`

Cada petición lleva la clave, que empieza por `utl_`:

```bash
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" }'
```

> **Atenció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**

1. **¿Está el Chat en el plan?** (Plan de tu organización): Lo comprueba el servidor en cada petición. Si no: 403 MODULE_NOT_ENABLED.
2. **¿Tiene el scope de la acción?** (Ficha de la aplicación): Por ejemplo, chat:messages:send para publicar. Si no: 403 INSUFFICIENT_SCOPE.
3. [**¿Tiene acceso a ese canal?**](https://os.utilia.ai/docs/developers/chat-platform/scopes-and-access) (Panel del canal): Una concesión activa que incluya esa acción. 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](https://os.utilia.ai/docs/developers/getting-started/errors-and-retries).

## 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](https://os.utilia.ai/docs/developers/chat-platform/scopes-and-access).