Abre Automatizaciones en la barra lateral izquierda y entra a la pestaña Llaves API. La página resume su trabajo en una línea: "Llaves públicas de API para acceso programático a tu cuenta. Cada llave se muestra completa solo al crearla; revócala y vuelve a crearla para rotarla." Una llave de aquí es una credencial de servidor a servidor: tu backend la manda en un encabezado HTTP y recibe JSON de vuelta. No es la llave que alimenta tu chat web insertado: esa vive en otra página, tiene otro prefijo y otras reglas, y la primera sección de abajo es toda la diferencia.
Dos tipos de llave, y no son intercambiables
IcloneU emite dos credenciales a las que todo el mundo llama llave de API. Viven en páginas distintas, protegen cosas distintas y cada una se rechaza donde va la otra. Treinta segundos aquí te ahorran una tarde de 401.
| Llave de chat web (hk-) | Llave API pública (ik-) | |
|---|---|---|
| Dónde se crea | Conexiones → Claves API | Automatizaciones → Llaves API |
| Para qué sirve | Un widget insertable, respondido por un Clon | Tu propio código leyendo y escribiendo los datos de tu cuenta |
| Quién la tiene | El navegador del visitante: se ve en el código de tu página | Tu servidor, y ningún otro lugar |
| Qué limita su alcance | Qué Clon responde | Uno de tres niveles de acceso, aplicado por endpoint |
| Cómo viaja | Dentro de la URL del fragmento de inserción | Un encabezado Authorization: Bearer ik-… |
| Cómo se rota | Eliminar la llave, crear otra, volver a insertar | Revocar la llave, crear otra, volver a desplegar |
| ¿Puede vencer sola? | No | Sí: tú eliges el plazo al crearla |
La API pública revisa el prefijo antes que cualquier otra cosa. Una petición cuyo encabezado no empieza con Bearer ik- se rechaza con un 401 y el código missing_api_key, aunque la llave de widget que lleve sea perfectamente válida. Tampoco funciona al revés: una llave ik- no sirve de nada para el widget de chat. La llave de widget tiene su propio recorrido: Crear y gestionar claves de API.
Crear una llave
Tres campos, un botón y un momento que no puedes repetir.
Abre la pestaña
Automatizaciones en la barra lateral izquierda y luego la pestaña Llaves API. Si no ves la pestaña, a tu rol en el equipo le falta Ver herramientas de desarrollador (conectores, llaves de API, webhooks), que es aparte de los permisos de Automatizaciones, o tu plan no la trae: la pestaña viene con todos los planes de pago. La entrada Automatizaciones del menú lateral requiere Ver automatizaciones, y crear y revocar llaves requiere Gestionar herramientas de desarrollador (conectores, llaves de API, webhooks).
Haz clic en Crear Llave
El botón está arriba a la derecha de la página y abre el diálogo Crear Llave API.
Ponle una Etiqueta
Etiqueta es el nombre que verás en la tabla, y el texto de ejemplo deja clara la idea: "ej. Make.com Producción". Nómbrala por el sistema que la va a guardar, porque esa es justo la pregunta que estarás respondiendo el día que decidas revocarla. Generar Llave queda deshabilitado hasta que la Etiqueta tiene algo escrito.
Elige el Nivel de Acceso
Nivel de Acceso ofrece Read Only, Standard y Full Access, y el diálogo abre en Standard. La siguiente sección dice exactamente qué compra cada uno.
AtenciónUna llave no tiene diálogo de edición. El nivel que elijas aquí es el que tendrá para siempre: cambiarlo significa crear una segunda llave y retirar la primera.
Elige el Vencimiento
Vencimiento ofrece Nunca vence, 30 días, 90 días y 1 año, contados desde el momento en que generas la llave. Un diálogo recién abierto arranca en Nunca vence; si ya creaste una llave sin salir de la página, el diálogo conserva lo que elegiste la vez anterior, así que revísalo antes de hacer clic.
AtenciónUn vencimiento es un interruptor de hombre muerto, no un recordatorio. Pasada la fecha, la API responde 401 key_expired y la insignia de la tabla cambia a Vencida, sin aviso previo y sin forma de extenderla.
Haz clic en Generar Llave y cópiala
La llave aparece una sola vez, en un diálogo que lo dice sin rodeos: "Copia esta llave ahora. No podrás verla de nuevo." Usa Copiar Llave, pégala directo en tu gestor de secretos y luego haz clic en Listo.
IcloneU guarda un hash SHA-256 de la llave más sus primeros ocho caracteres: lo suficiente para reconocerla cuando vuelve y para mostrarte un fragmento en la tabla, y no lo suficiente para reconstruirla. Nadie te la puede leer de vuelta: ni la tabla, ni soporte, ni una consulta a la base de datos. Si se pierde, el único camino es revocar y crear otra.
Qué controlan de verdad los tres niveles de acceso
El nivel se revisa por endpoint, no por recurso, y la división es tosca a propósito: las lecturas están abiertas a cualquier llave, las escrituras normales piden Standard y dos áreas piden Full Access.
| Nivel de Acceso | Qué puede hacer una llave de este nivel |
|---|---|
| Read Only | Todas las lecturas. Listar y abrir clones, flujos, contactos, conversaciones y sus mensajes, campos personalizados, plataformas conectadas, etiquetas, reseñas y suscripciones de webhook. No puede cambiar absolutamente nada. |
| Standard | Todo lo anterior, más las escrituras normales: crear y actualizar un contacto, agregar o quitar sus etiquetas, archivar un contacto (DELETE, que solo se deshace en la app con Restaurar contacto) o borrarlo para siempre, crear una etiqueta y publicar un mensaje en una conversación. |
| Full Access | Todo lo anterior, más las dos áreas privilegiadas: cambiar el estado de un flujo y todas las escrituras de suscripciones de webhook: crear, actualizar, eliminar, enviar prueba, rotar secreto y reenviar. |
Una llamada que pide más de lo que la llave trae se rechaza con un 403 y el código insufficient_permissions, y el mensaje nombra lo que faltaba: "This API key does not have full access. Required: Full Access tier." Nada parcial ocurre antes: la revisión corre antes de cambiar cualquier cosa.
Read Only, Standard y Full Access son los nombres en el diálogo, en la insignia de la tabla, en el mensaje de rechazo de la propia API y en esta guía. No están traducidos: una sesión en español muestra los mismos tres nombres en inglés. Léelos como identificadores, no como etiquetas.
Qué alcanza una llave
Todo cuelga de /api/public en tu propia dirección de IcloneU, y cada ruta está acotada a la cuenta donde se creó la llave: un id que pertenece a otra cuenta responde 404, no datos.
- Clones (/assistants) — lista tus Clones y abre uno.
- Automatizaciones (/automations) — lista tus flujos, abre uno y (con Full Access) cambia el estado de un flujo.
- Contactos (/contacts) — lista, abre, crea, actualiza, archiva (DELETE) y borra un contacto, y agrega o quita sus etiquetas.
- Conversaciones (/conversations) — lista, abre una, lee sus mensajes y publica un mensaje en ella. La lista va de la creada más recientemente a la más antigua, 25 por página por defecto. Sin min_time cubre los últimos 30 días; min_time y max_time se comparan con el last_updated_at de cada conversación, o con su created_at si no tiene. Deja fuera las conversaciones sin mensajes salvo que pases include_empty=true. Al abrir una conversación recibes sus mensajes en una sola respuesta, del más antiguo al más reciente, sin paginar; /conversations/{id}/messages devuelve los mismos mensajes por páginas, 50 por página por defecto.
- Campos personalizados (/custom-fields) — lista los campos personalizados definidos en tu cuenta.
- Plataformas (/platforms) — lista las cuentas de plataforma que tienes conectadas.
- Etiquetas (/tags) — lista y crea.
- Reseñas (/reviews) — el resumen, la lista y el esquema detrás de ellos.
- Webhooks (/webhooks) — toda la superficie de suscripciones salientes, cubierta en Suscripciones de webhook.
Cinco listados van paginados (contactos, conversaciones, los mensajes de una conversación, automatizaciones y las entregas de un webhook) y aceptan page y per_page. Un tamaño de página mayor a 100 se recorta a 100 en vez de rechazarse, y la respuesta trae un bloque meta con page, per_page, total y total_pages, así que puedes recorrer el conjunto completo sin adivinar. Las reseñas aceptan per_page hasta 50 sin bloque meta, y los demás listados (Clones, campos personalizados, plataformas, etiquetas y suscripciones de webhook) devuelven todo de una vez.
Explórala en /api/public/docs —una referencia completa petición por petición, con un enlace Download openapi.json— o baja la especificación legible por máquina desde /api/public/openapi.json y apunta ahí tu generador de clientes. Ambas están abiertas sin llave. Antepón tu dirección de IcloneU a cualquiera de las dos rutas.
Las llamadas están limitadas a 60 por minuto por llave, en una ventana fija de un minuto y sin cola: la petición 61 recibe 429 de inmediato en vez de esperar. El presupuesto es de la llave, así que separar un proceso ruidoso en su propia llave evita que se coma el de tu integración.
Cómo leer la tabla
Cinco columnas —Etiqueta, Llave, Acceso, Último Uso y Creada— y el estado vive dentro de la primera.
- Etiqueta lleva una insignia junto al nombre: Activa, Vencida cuando la fecha de vencimiento ya pasó, o Revocada. La insignia y la API coinciden: una llave que la tabla llama Vencida es una llave que la API ya está rechazando.
- Llave muestra los primeros ocho caracteres y unos puntos suspensivos. Eso es el prefijo ik- más cinco caracteres: suficiente para distinguir dos llaves en un archivo de configuración, e insuficiente para ser una credencial.
- Acceso es el nivel elegido al crearla.
- Último Uso se sella en cada petición que la llave logra pasar, así que es la respuesta honesta a la única pregunta que importa antes de revocar: ¿todavía hay algo llamando con esta? Una llave que nunca se ha usado dice Never — en inglés, en los dos idiomas de la interfaz.
- Creada es la fecha en que se generó la llave. Una fila revocada se queda en la lista con la etiqueta Revocada en vez de desaparecer.
El Vencimiento que eliges se guarda y se aplica, pero ninguna pantalla te lo devuelve. No es una columna de la tabla, no está en el diálogo de una sola vez y no hay diálogo de edición para volver a abrirlo. Si no lo anotas tú al crear la llave, la primera señal de que una llave de 90 días ya caducó será un 401 key_expired en tus propios registros. Guarda la fecha junto a la llave, donde sea que guardes tus secretos.
Rotar, revocar y los errores que vas a ver
No hay botón de regenerar ni de revelar. Rotar es revocar y crear otra, y como revocar surte efecto en la siguiente petición, el orden en que lo hagas decide si algo se cae.
Crea primero la llave de reemplazo
Mismo Nivel de Acceso y una Etiqueta que diga de qué generación es. Despliégala donde guardas tus secretos y deja que el tráfico se mueva.
Confirma que la llave vieja ya se calló
Vigila Último Uso en la fila vieja. Mientras siga moviéndose, algo sigue llamando con ella: revocar ahora es una caída, no una rotación.
Selecciona la llave vieja y haz clic en Revocar
La confirmación es específica sobre el alcance: "¿Estás seguro de que quieres revocar la llave "{0}"? Cualquier integración que use esta llave dejará de funcionar inmediatamente." Confirma y listo: no hay deshacer ni papelera de reciclaje.
Nada te avisa antes de la fecha de vencimiento y nada te deja empujarla. El arreglo para una llave por vencer es el mismo que para una filtrada: crear el reemplazo, mover el tráfico y luego revocar. Si no puedes comprometerte con esa rutina, elige Nunca vence y rota en tu propio calendario.
| Qué regresa | Qué significa |
|---|---|
| 401 missing_api_key | Falta el encabezado Authorization, o no empieza con Bearer ik-. Una llave de chat web hk- cae aquí. |
| 401 invalid_api_key | La llave no tiene forma de llave ik- válida, o no existe ninguna llave con esa huella en ninguna cuenta. |
| 401 key_revoked | La llave existe y fue revocada. |
| 401 key_expired | La llave pasó el Vencimiento elegido al crearla. |
| 403 insufficient_permissions | La llave es real pero su Nivel de Acceso está por debajo de lo que pide ese endpoint. |
| 403 plan_required | La cuenta no tiene un plan activo o de prueba, por ejemplo porque la suscripción venció. La llave se conserva y vuelve a funcionar unos 10 minutos después de renovar. |
| 404 not_found | No existe ese id en esta cuenta. La misma respuesta si el registro nunca existió o si es de alguien más. |
| 429 | Más de 60 peticiones de esta llave dentro del mismo minuto. |
| 400 validation_error | A la petición le falta algo obligatorio o trae un valor fuera de rango, por ejemplo un mensaje vacío o más de 50 campos personalizados; el mensaje dice cuál. |
| 502 delivery_error | IcloneU tuvo un error propio al procesar el envío. En todos los canales salvo Chat web eso significa que el mensaje no se entregó, así que puedes reintentar; en Chat web puede que ya esté en la conversación. Cuando un canal acepta un mensaje, la respuesta nunca es un error: es 200 con delivery_status delivered, y con id 0 en el caso raro de que IcloneU no pudiera registrarlo (el cliente lo recibió, pero no aparece en la conversación). Un mensaje entregado también dispara el evento de webhook message.sent.v1, con sent_by: api. Un mensaje que el canal rechaza tampoco es un error: la respuesta es 200 con delivery_status undeliverable o failed, y el mensaje queda registrado en la conversación. Así que reintenta solo ante una respuesta de error. |
| 500 internal_error | La llamada llegó a IcloneU y falló adentro. Es seguro reintentar. |
Preguntas frecuentes
No. Una llave no tiene diálogo de edición: la única acción de fila es Revocar. Las dos decisiones se toman una sola vez, al crearla. Cambiar cualquiera de las dos significa crear una llave nueva y retirar la vieja.
No. Una llave API pública es de toda la cuenta por diseño; la vinculación a un Clon pertenece al modelo de la llave de chat web. Lo que sí puedes variar es el nivel de acceso, así que un proceso de reportes de solo lectura y un proceso de sincronización con escritura deberían tener llaves distintas.
La pestaña registra una sola cosa: Último Uso, actualizado en cada petición que la llave logra pasar. No hay un registro de peticiones por llave en el producto, así que trata Último Uso como una señal de vida: sirve para decidir si una llave se puede revocar sin riesgo, no como bitácora de auditoría.
No. La fila se queda en la tabla con la etiqueta Revocada, pero la llave está terminada: cada petición con ella responde 401 key_revoked. Crea un reemplazo y despliégalo.
No. /api/public/docs y /api/public/openapi.json se dejaron abiertas a propósito, para que puedas leer la referencia y generar un cliente antes de crear tu primera llave. Cada endpoint de datos bajo /api/public sí necesita una.
Última actualización: octubre 6, 2026 · Automatizaciones
