Construir
ES
Unipile MCP · Hosted Auth

Unipile Hosted Auth, implementado por su agente de código

Sus usuarios vinculan su propia cuenta de LinkedIn, WhatsApp o email en una página alojada por Unipile. Con el Servidor MCP de Unipile, su agente escribe la ruta y el callback.
Implemente Hosted Auth con un agente Documentación de Hosted Auth
Prueba gratis de 7 días, sin tarjeta.
Su agente · crm-app
Unipile MCP conectado
Sarah
Implementa Unipile Hosted Auth en esta app React y Fastify.
Leer endpointPOST /v2/auth/linkesquema cargado
Se han añadido la ruta del enlace y el callback. El ID de la cuenta se guarda en el workspace.
4 archivos modificados · probado con providers: "mock"
Describa la próxima función…
El objetivo

Lo que quiere conseguir

Permita que cada usuario de su producto conecte sus propias cuentas, sin que su código vea nunca una contraseña ni un token, y recupere el ID de cuenta que necesitarán todas las peticiones posteriores. Cada proveedor tiene su propio inicio de sesión, su paso de doble factor y su pantalla de consentimiento. Hosted Auth reúne todo eso en una única página servida por Unipile, y el agente conecta las tres piezas que dependen de su aplicación.
Sin ello Formularios de login, tokens, rarezas de cada proveedor
Construye un formulario de login por proveedor y almacena tokens que nunca quiso custodiar.
Las peticiones de doble factor y las pantallas de consentimiento rompen el flujo de forma distinta en cada proveedor.
El ID de cuenta acaba deducido de la redirección, y se pierde cuando el usuario cierra la pestaña.
Con el servidor MCP de Unipile El resultado en su aplicación
Un botón Conectar que abre el asistente alojado, y una ruta de callback que guarda el ID de cuenta en el workspace.
Un botón Reconectar que reutiliza el mismo endpoint con el ID de cuenta almacenado.
El flujo validado con el proveedor mock en su aplicación de Development antes de vincular una cuenta real.
Prompt, pasos, código

Dé el prompt a su agente

Dos prompts, cada uno con los endpoints de Unipile que el agente lee y ejecuta y lo que llega a su proyecto. Las rutas están completas, sobre la URL base de la API https://api.unipile.com, con su clave con scope en la cabecera X-API-KEY .
Su agente · crm-appApp de Development
Implementa Unipile Hosted Auth en esta aplicación React y Fastify: una ruta de servidor que crea el enlace de autenticación, una ruta de callback que lee account_id y state, y la persistencia del account_id en el workspace actual.
Leer endpointPOST /v2/auth/linkesquema cargado
Ejecutar peticiónPOST /v2/auth/link201 · link
Se ha añadido POST /api/accounts/connect en Fastify: llama al endpoint de enlace de autenticación con providers, un expires_on fijado a quince minutos en ISO 8601 UTC, el redirect_uri del callback y un state firmado que lleva el ID del workspace. La página de Ajustes en React abre la URL devuelta en link. GET /auth/callback lee account_id, provider y state de la query y guarda la cuenta. Probado con providers: "mock" en la app de Development.4 archivos modificados · flujo de conexión probado

Un enlace creado en el servidor, un callback que guarda el ID de la cuenta

El enlace se crea en su servidor con su clave con scope; el navegador solo recibe la URL alojada. Cuando el usuario termina, Unipile redirige a su redirect_uri con account_id, provider y su state en la query string. El agente lee estos tres campos en el contrato, no de memoria, y escribe el callback en consecuencia.
Endpoints que usa el agente
POST/v2/auth/linkGET/v2/accounts/{account_id}GET/v2/accounts/
Error frecuente: Crear el enlace de autenticación desde el navegador. La clave quedaría expuesta; el frontend solo abre el enlace que devuelve su servidor.
Referencia del enlace de autenticación
Su agente · crm-appApp de Development
Añade un botón Reconectar junto a cada cuenta conectada: llama al endpoint de enlace de autenticación de Unipile en modo de reautenticación con el account_id guardado y gestiona el callback igual que en la primera conexión.
Leer endpointPOST /v2/auth/linkrama de reautenticación
Ejecutar peticiónGET /v2/accounts/{account_id}status: disconnected
Se ha añadido POST /api/accounts/:id/reconnect: mismo endpoint, mismo redirect_uri, pero el body lleva account_id en lugar de providers. La página de Ajustes muestra el botón cuando el estado de la cuenta no es running, y el callback existente gestiona el regreso. Verificado desconectando la cuenta mock en la app de Development.2 archivos modificados · reutiliza el callback de la primera conexión

Mismo endpoint, cambia un solo campo

Un enlace de reconexión lleva account_id y no providers; una primera conexión lleva providers y no account_id. El contrato indica que se actualiza toda la cuenta y que se reinician todos los productos configurados, así que el agente lo lanza a partir del estado de la cuenta y mantiene un único callback para ambos flujos.
Endpoints que usa el agente
POST/v2/auth/linkGET/v2/accounts/{account_id}POST/v2/auth/checkpoint
Error frecuente: Enviar a la vez providers y account_id. El body lleva una rama u otra, nunca las dos.
Lanzarlo a partir de account.status.disconnected
Payload

El body de la petición, ambas ramas y la respuesta

Literal del contrato v2 que el agente lee a través del servidor. Tres campos son obligatorios para una primera conexión, y la respuesta es un único enlace.
1Vincular una cuenta nuevaproviders, expires_on y redirect_uri son obligatorios. state se devuelve en la redirección y en el evento account.add. account_scope_id asigna la cuenta a un Scope.POST https://api.unipile.com/v2/auth/link { "providers": "*", "expires_on": "2026-10-01T12:00:00.000Z", "redirect_uri": "https://app.example.com/auth/callback", "state": "ws_42.signed", "account_scope_id": "scope_…" }
2Reautenticar una cuenta existenteaccount_id sustituye a providers. Toda la cuenta se renueva y todos los productos configurados se reinician.POST https://api.unipile.com/v2/auth/link { "account_id": "acc_…", "expires_on": "2026-10-01T12:00:00.000Z", "redirect_uri": "https://app.example.com/auth/callback" }
3Respuesta y retornoLa respuesta es un HostedAuthLink. Tras el asistente, la redirección lleva account_id, provider y state; el webhook account.add lleva el mismo state.{ "object": "HostedAuthLink", "link": "https://auth.unipile.com/…" } GET https://app.example.com/auth/callback?account_id=acc_…&provider=linkedin&state=ws_42.signed
De Development a producción

Pruebe primero en una aplicación de Development

Su dashboard de Unipile separa la aplicación de Development de la de Production. Dé al agente una clave con scope de Development y use el proveedor mock: todo el flujo, sin ninguna cuenta real.
1Ejecute el flujo con providers: "mock"Enlace creado en el servidor, callback leído, ID de cuenta almacenado.
2Reconecte la cuenta de pruebaDesconéctela, abra el enlace de reconexión, estado de vuelta en running.
3Confirme account.add y cambie luego de claveEl webhook lleva el mismo state que la redirección; solo entonces pase a Production.
crm-app · DevelopmentUsada por su agente
Scopedev-tests · 2 cuentas
Clavescoped Account API key
CuentasCuenta de prueba LinkedIn, buzón de prueba Gmail
Webhooks1 endpoint · eventos de mensaje
crm-app · ProductionSin tocar
Scopeuno por workspace
Clavescoped keys, in your backend only
Cuentaslas cuentas propias de sus usuarios, vía Hosted Auth
Resolución de problemas

Errores habituales y qué significan

Los cuatro fallos que bloquean una integración de Hosted Auth, y cómo se corrige cada uno. La mayoría vienen de copiar un ejemplo de v1.
notify_url o success_redirect_url en el body
La petición se rechaza, o el callback nunca se dispara. SoluciónSon campos de v1. El body de v2 acepta redirect_uri y state; las notificaciones pasan por un endpoint de webhook suscrito a account.add y account.reconnect.
expires_on rechazado
Error de validación en la fecha. SoluciónEl campo espera un datetime ISO 8601 en UTC, YYYY-MM-DDTHH:MM:SS.sssZ. Un timestamp Unix o una fecha local se rechazan.
Las dos ramas en un mismo body
Error de validación en providers o account_id. SoluciónUna primera conexión lleva providers y no account_id; una reconexión lleva account_id y no providers. Envíe una sola rama.
El ID de cuenta nunca llega
El usuario cerró la pestaña antes de la redirección. SoluciónLa redirección es una comodidad. La fuente de verdad es el evento account.add en su endpoint de webhook, que lleva el mismo state. Guarde desde el evento, confirme desde la redirección.
6000+ Empresas que innovan con Unipile
La confianza de los líderes del sector
1 API
Racionalizar las operaciones de los principales canales de comunicación
2 días
Rápida integración en directo con una configuración mínima
30%
Reducción de los esfuerzos y recursos de mantenimiento

Seguridad y conformidad integradas

Protección de nivel empresarial para sus datos y flujos de trabajo Más información sobre nuestra seguridad
SOC 2 Tipo II
SOC 2 Tipo II
Certificado
Controles de seguridad auditados de forma independiente que garantizan la protección de datos y la integridad operativa.
GDPR
GDPR
Conforme
Pleno cumplimiento de la normativa europea de protección de datos para la privacidad de los usuarios.
99.9%
Tiempo de actividad de la plataforma en los últimos 24 meses
24/7
Asistencia global con API de alto rendimiento

FAQ de Hosted Auth

Qué es Hosted Auth, qué endpoint crea el enlace, cómo saber si el usuario ha terminado, cómo reconectar y qué proveedores puede mostrar el asistente.
Una página alojada por Unipile donde su usuario se autentica con su proveedor. Usted crea un enlace con POST /v2/auth/link, redirige al usuario a él y recibe un account_id. Las credenciales y los tokens nunca pasan por su código.
POST https://api.unipile.com/v2/auth/link, con la cabecera X-API-KEY y un body que lleva providers, expires_on y redirect_uri. No existe ninguna ruta /v2/hosted/accounts/link en v2.
Dos canales. El redirect_uri recibe account_id, provider y state como parámetros de query. El evento account.add del webhook lleva el mismo state. Use el webhook como fuente de verdad y la redirección para la experiencia de usuario.
El mismo endpoint, con account_id en lugar de providers. El contrato indica que toda la cuenta se renueva y que todos los productos configurados se reinician. Dispare el flujo desde el evento account.status.disconnected o desde el estado de la cuenta.
providers acepta *, un filtro de familia como *:EMAILS, *:MESSAGING, *:CALENDAR o *:SOCIAL, o una lista entre linkedin, whatsapp, google, outlook, imap, telegram y instagram. Use mock para probar el flujo.