Elegir credencial
Las seis credenciales de UTILIA OS, qué abre cada una y cuál te toca según quién llama: tu aplicación, un programa, una IA o tu web.
Actualizado el . 4 min de lectura
Incluido en todos los planes. Ver precios
UTILIA OS tiene seis credenciales y cada una abre solo su puerta: con la equivocada, la respuesta es un 401, por bien escrita que esté la petición. Elegir bien depende de una sola cosa, quién llama y en nombre de quién.
Cuál te toca
¿Qué credencial necesitas?
¿Quién va a llamar a UTILIA OS?
Un programa de tu empresa:
Clave de API de la organización
Authorization: Bearer utk_…
Scripts, cuadros de mando y automatizaciones con tus datos, con los permisos de una persona de tu equipo.Tu aplicación:
¿En nombre de quién trabaja?
Cada persona que la usa:
Authorization: Bearer
La persona entra con su cuenta de UTILIA OS y autoriza a tu aplicación.Empresas que la instalan:
X-Api-Key: utl_…
Una por empresa, que recibe tu servidor al instalarla desde el catálogo.Tus propios usuarios:
¿Abre desde el navegador una conexión de eventos en tiempo real?
Sí:
?streamToken=…
Lo pide tu servidor con la clave de la aplicación; vale para una conexión.No:
X-Api-Key: utl_…
Tu servidor llama a la API externa con sus usuarios, tickets, facturas y cobros.
Un asistente de IA:
Authorization: Bearer
Claude, ChatGPT o Cursor por MCP, con los permisos de quien lo conecta.Tu web, para captar leads:
Si solo quieres poner un formulario de captación o el widget de soporte en tu web, no necesitas escribir ninguna petición: se insertan con un fragmento de código. Lo explican Insertar un formulario y el widget de soporte.
Las seis de un vistazo
| Credencial | Cómo viaja | Dónde nace | Qué abre | Quién actúa |
|---|---|---|---|---|
Clave de aplicación externa (utl_…) | Cabecera X-Api-Key | Al crear la aplicación, en Ajustes › Creadas por tu empresa | La API externa (/api/external/v1), con los permisos de la API de la aplicación | La aplicación, a nombre de su persona responsable |
Clave de instalación del catálogo (utl_…) | Cabecera X-Api-Key | La recibe tu servidor, una por empresa, al canjear el código de su instalación | La API externa, con los permisos que concedió esa empresa | La persona responsable que eligió la empresa, nunca con más |
Clave de API de la organización (utk_…) | Authorization: Bearer | Ajustes › Claves de API, tipo «Acceso a la API» | Las rutas que usa la aplicación (/api/...), recortadas por la clave | Su persona responsable, nunca con más permisos que ella |
| Token de OAuth | Authorization: Bearer | Lo autoriza una persona desde tu aplicación o tu asistente de IA | Lo que esa persona autoriza, como los servidores MCP | La persona que autoriza |
Clave para enviar leads (utl_…) | Cabecera X-API-Key | Ajustes › Claves de API, tipo «Enviar leads desde tu web» | Solo POST /api/v1/leads | La clave; los leads se asignan a quien la creó |
| Pase de conexión | Parámetro streamToken | Lo pide tu servidor con la clave de la aplicación | Una conexión de eventos en tiempo real, durante cinco minutos | La aplicación |
La clave de aplicación, la de una instalación y la de enviar leads empiezan por utl_: el prefijo no basta para distinguirlas. Lo que las distingue es dónde nacen y la puerta que abren.
Dónde vive cada una
- Solo en tu servidor: la clave de API de la organización, la de enviar leads, la de una aplicación con permisos de servidor y las de cada instalación del catálogo. UTILIA OS rechaza la clave de la organización cuando la petición llega desde un navegador.
- En una página web, con límites: la clave de una aplicación con dominios autorizados, como la del widget, que solo admite los siete permisos del navegador. Lo explica Claves dentro de una página web.
- En el navegador, de paso: el pase de conexión y el token de OAuth de una aplicación sin servidor, que se protege con PKCE.
Si algo falla
401 API_KEY_WRONG_KIND: la clave es de otro tipo que la puerta. Por ejemplo, unautk_en la API externa, o unautl_enAuthorization: Bearerhacia/api/....401 API_KEY_WRONG_HEADER: la clave de la aplicación va enAuthorization: Bearer; va enX-Api-Key.401 API_KEY_NOT_LINKED: una clave para enviar leads llama a la API externa, que es solo para claves de aplicación.401 API_KEY_IN_URL_NOT_ALLOWED: la clave va en la dirección. Muévela a su cabecera o usa un pase de conexión.
La lista completa, con qué hacer en cada caso, está en Qué credencial abre cada puerta y en Errores y reintentos.