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

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**](https://os.utilia.ai/docs/developers/organization-api-keys/overview) (`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: [**Token de OAuth**](https://os.utilia.ai/docs/developers/oauth/overview) (`Authorization: Bearer`). La persona entra con su cuenta de UTILIA OS y autoriza a tu aplicación.
  - Empresas que la instalan: [**Clave de instalación**](https://os.utilia.ai/docs/developers/apps-platform/installation-and-exchange) (`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í: [**Pase de conexión**](https://os.utilia.ai/docs/developers/getting-started/authentication#eventos-en-tiempo-real-un-pase-en-lugar-de-la-clave) (`?streamToken=…`). Lo pide tu servidor con la clave de la aplicación; vale para una conexión.
    - No: [**Clave de aplicación externa**](https://os.utilia.ai/docs/developers/getting-started/authentication) (`X-Api-Key: utl_…`). Tu servidor llama a la API externa con sus usuarios, tickets, facturas y cobros.
- Un asistente de IA: [**Token de OAuth**](https://os.utilia.ai/docs/developers/mcp/quickstart) (`Authorization: Bearer`). Claude, ChatGPT o Cursor por MCP, con los permisos de quien lo conecta.
- Tu web, para captar leads: [**Clave para enviar leads**](https://os.utilia.ai/docs/developers/lead-forms/leads-api) (`X-API-Key: utl_…`). Solo da de alta leads en tu CRM, desde tu servidor.

_Cada resultado lleva a la página que la explica._

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](https://os.utilia.ai/docs/developers/lead-forms/embed) y el [widget de soporte](https://os.utilia.ai/docs/developers/widget/overview).

## 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](https://os.utilia.ai/docs/developers/getting-started/rate-limits-and-cors#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, una `utk_` en la API externa, o una `utl_` en `Authorization: Bearer` hacia `/api/...`.
- **`401 API_KEY_WRONG_HEADER`**: la clave de la aplicación va en `Authorization: Bearer`; va en `X-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](https://os.utilia.ai/docs/developers/getting-started/authentication#qué-credencial-abre-cada-puerta) y en [Errores y reintentos](https://os.utilia.ai/docs/developers/getting-started/errors-and-retries).

## Siguiente paso

- [Primeros 15 minutos con la API](https://os.utilia.ai/docs/developers/getting-started/quickstart): Con la clave de una aplicación externa: un usuario, un ticket y sugerencias de IA.
- [Tu primera petición con una clave de la organización](https://os.utilia.ai/docs/developers/organization-api-keys/first-request): Pregúntale a la clave quién es y qué puede hacer.