Autenticación con clave de acceso

La API externa (https://os.utilia.ai/api/external/v1/...) reconoce a tu aplicación por su clave de API, que envías en la cabecera X-Api-Key en cada petición. No hay sesión, ni cookies, ni token que renovar: la clave basta, y por eso solo debe vivir en tu servidor.

GET /api/external/v1/users HTTP/1.1
Host: os.utilia.ai
X-Api-Key: utl_tu_clave

De dónde sale la clave

Cada aplicación externa tiene una clave propia, que se genera al crearla en Ajustes › Integraciones › Aplicaciones externas, necesitas entrar con tu cuenta. Empieza por utl_ y solo se muestra una vez, en la pantalla «Aplicación creada». UTILIA OS guarda únicamente su huella, así que nadie puede volver a enseñártela.

Si la pierdes o sospechas que se ha filtrado, regenérala desde la ficha de la aplicación, en Ajustes. La clave anterior deja de funcionar en ese mismo momento, así que despliega la nueva antes de que tu integración vuelva a llamar. Hoy solo puede regenerarla la persona que creó la aplicación.

Qué se comprueba en cada petición

Antes de llegar a la operación, cada petición pasa estos controles, en este orden. El primero que falla corta la petición con su código:

Cada código de error está explicado en Errores, identificador de petición y reintentos. La organización con la que trabaja la petición sale siempre de la aplicación dueña de la clave, nunca de lo que envíes en el cuerpo.

Los límites de uso y los orígenes permitidos se explican en Límites de uso y CORS.

La clave en la dirección, solo para eventos en tiempo real

EventSource, la herramienta del navegador para recibir eventos en tiempo real, no permite añadir cabeceras. Por eso, y solo en peticiones GET con Accept: text/event-stream, la API acepta la clave como parámetro apiKey de la dirección:

const fuente = new EventSource(
  `https://os.utilia.ai/api/external/v1/tickets/ai-suggest/${jobId}/stream?apiKey=${clave}`,
);

En cualquier otra petición se ignora y la respuesta es 401 API_KEY_REQUIRED. Una dirección queda escrita en registros de servidores, proxies e historiales, así que úsala solo desde tu servidor o desde un intermediario que controles. El SDK de JavaScript ya lo hace así en sus suscripciones en tiempo real.

Qué credencial abre cada puerta

UTILIA OS reconoce tres credenciales distintas, y cada una solo abre su puerta. Si envías a la API externa una clave de Ajustes › Claves de acceso (API), la respuesta es 401 con API_KEY_NOT_LINKED.

La API del panel (por ejemplo, /api/integrations/apps/..., que gestiona las aplicaciones externas) se llama con Authorization: Bearer <token> y los permisos de la persona. Una clave de API no la abre.

Siguiente paso

Revisa cuántas peticiones admite tu clave y cómo se controla desde qué webs se puede llamar en Límites de uso y CORS.