Démarrer
FR
Unipile MCP · Hosted Auth

Unipile Hosted Auth, implémenté par votre agent de codage

Vos utilisateurs lient leur propre compte LinkedIn, WhatsApp ou email sur une page hébergée par Unipile. Avec le serveur MCP Unipile, votre agent écrit la route et le callback.
Implémenter Hosted Auth avec un agent Documentation Hosted Auth
Essai gratuit de 7 jours, sans carte bancaire.
Votre agent · crm-app
MCP Unipile connecté
Sarah
Implémente Unipile Hosted Auth dans cette app React et Fastify.
Lecture de l'endpointPOST /v2/auth/linkschéma chargé
Route du lien et callback ajoutés. L'ID du compte est enregistré sur le workspace.
4 fichiers modifiés · testé avec providers: "mock"
Décrivez la fonctionnalité suivante…
La mission

Ce que vous cherchez à faire

Permettre à chaque utilisateur de votre produit de connecter ses propres comptes, sans que votre code voie jamais un mot de passe ou un token, et récupérer l'account ID dont chaque requête suivante a besoin. Chaque provider a son propre login, son étape de double authentification et son écran de consentement. Hosted Auth regroupe tout cela sur une page servie par Unipile, et l'agent câble les trois éléments qui appartiennent à votre app.
Sans lui Formulaires de login, tokens, particularités des providers
Vous construisez un formulaire de login par provider et stockez des tokens que vous ne vouliez pas détenir.
Les demandes de double authentification et les écrans de consentement cassent le parcours différemment selon le provider.
L'account ID finit déduit de la redirection, et perdu quand l'utilisateur ferme l'onglet.
Avec le serveur MCP Unipile Le résultat dans votre application
Un bouton Connecter qui ouvre l'assistant hébergé, et une route de callback qui enregistre l'account ID sur le workspace.
Un bouton Reconnecter qui réutilise le même endpoint avec l'account ID enregistré.
Le parcours validé avec le provider mock sur votre application Development avant de lier un vrai compte.
Prompt, étapes, code

Donnez le prompt à votre agent

Deux prompts, chacun avec les endpoints Unipile que l'agent lit et exécute, et ce qui arrive dans votre projet. Les chemins sont complets, sur l'URL de base de l'API https://api.unipile.com, avec votre clé scopée dans l'en-tête X-API-KEY .
Votre agent · crm-appApp Development
Implémente Unipile Hosted Auth dans cette application React et Fastify : une route serveur qui crée le lien d'authentification, une route de callback qui lit account_id et state, et l'enregistrement de l'account_id sur le workspace courant.
Lecture de l'endpointPOST /v2/auth/linkschéma chargé
Exécution de la requêtePOST /v2/auth/link201 · lien
Ajout de POST /api/accounts/connect dans Fastify : elle appelle l'endpoint du lien d'authentification avec providers, un expires_on à quinze minutes en ISO 8601 UTC, le redirect_uri du callback et un state signé qui porte l'ID du workspace. La page Paramètres React ouvre l'URL renvoyée dans link. GET /auth/callback lit account_id, provider et state dans la query string et enregistre le compte. Testé avec providers: "mock" sur l'app Development.4 fichiers modifiés · parcours de connexion testé de bout en bout

Un lien créé côté serveur, un callback qui enregistre l'account ID

Le lien est créé sur votre serveur avec votre clé scopée ; le navigateur ne reçoit que l'URL hébergée. Quand l'utilisateur a terminé, Unipile redirige vers votre redirect_uri avec account_id, provider et votre state dans la query string. L'agent lit ces trois champs dans le contrat, pas de mémoire, et écrit le callback en conséquence.
Endpoints utilisés par l'agent
POST/v2/auth/linkGET/v2/accounts/{account_id}GET/v2/accounts/
Erreur fréquente : Créer le lien d'authentification depuis le navigateur. La clé fuiterait ; le frontend ouvre seulement le lien renvoyé par votre serveur.
Référence du lien d'authentification
Votre agent · crm-appApp Development
Ajoute un bouton Reconnecter à côté de chaque compte connecté : appelle l'endpoint de lien d'authentification Unipile en mode réauthentification avec l'account_id enregistré, et gère le callback comme pour la première connexion.
Lecture de l'endpointPOST /v2/auth/linkbranche réauthentification
Exécution de la requêteGET /v2/accounts/{account_id}status: disconnected
Ajout de POST /api/accounts/:id/reconnect : même endpoint, même redirect_uri, mais le body contient account_id au lieu de providers. La page Paramètres affiche le bouton quand le statut du compte n'est pas running, et le callback existant gère le retour. Vérifié en déconnectant le compte mock sur l'app Development.2 fichiers modifiés · réutilise le callback de la première connexion

Même endpoint, un seul champ change

Un lien de reconnexion prend account_id et aucun providers ; une première connexion prend providers et aucun account_id. Le contrat indique que tout le compte est rafraîchi et que chaque produit configuré redémarre : l'agent le déclenche donc à partir du statut du compte et garde un seul callback pour les deux parcours.
Endpoints utilisés par l'agent
POST/v2/auth/linkGET/v2/accounts/{account_id}POST/v2/auth/checkpoint
Erreur fréquente : Envoyer à la fois providers et account_id. Le body suit une branche ou l'autre, jamais les deux.
Le déclencher depuis account.status.disconnected
Payload

Le body de la requête, les deux branches et la réponse

Tel quel, depuis le contrat v2 que l'agent lit via le serveur. Trois champs sont obligatoires pour une première connexion, et la réponse est un simple lien.
1Lier un nouveau compteproviders, expires_on et redirect_uri sont obligatoires. state est renvoyé dans la redirection et dans l'événement account.add. account_scope_id rattache le compte à 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_…" }
2Réauthentifier un compte existantaccount_id remplace providers. Tout le compte est rafraîchi et chaque produit configuré redémarre.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" }
3Réponse et retourLa réponse est un HostedAuthLink. Après l'assistant, la redirection porte account_id, provider et state ; le webhook account.add porte le même state.{ "object": "HostedAuthLink", "link": "https://auth.unipile.com/…" } GET https://app.example.com/auth/callback?account_id=acc_…&provider=linkedin&state=ws_42.signed
Du développement à la production

Testez d'abord sur une application Development

Votre dashboard Unipile sépare une application Development de la Production. Donnez à l'agent une clé scopée issue de Development et utilisez le provider mock : tout le parcours, sans aucun vrai compte.
1Lancez le parcours avec providers: "mock"Lien créé côté serveur, callback lu, account ID enregistré.
2Reconnectez le compte de testDéconnectez-le, ouvrez le lien de reconnexion, le statut repasse à running.
3Confirmez account.add, puis changez de cléLe webhook porte le même state que la redirection ; passez en Production seulement ensuite.
crm-app · DevelopmentUtilisée par votre agent
Scopedev-tests · 2 comptes
Cléclé Account API scopée
ComptesCompte LinkedIn de test, boîte mail Gmail de test
Webhooks1 endpoint · événements de message
crm-app · ProductionIntacte
Scopeun par workspace
Cléclés scopées, uniquement dans votre backend
Comptesles propres comptes de vos utilisateurs, via Hosted Auth
Dépannage

Erreurs fréquentes et leur signification

Les quatre erreurs qui bloquent une intégration Hosted Auth, et la correction de chacune. La plupart viennent d'un exemple v1 recopié.
notify_url ou success_redirect_url dans le body
La requête est rejetée, ou le callback ne se déclenche jamais. CorrectionCe sont des champs v1. Le body v2 prend redirect_uri et state ; les notifications passent par un endpoint webhook abonné à account.add et account.reconnect.
expires_on rejeté
Erreur de validation sur la date. CorrectionLe champ attend une date-heure ISO 8601 UTC, YYYY-MM-DDTHH:MM:SS.sssZ. Un timestamp Unix ou une date locale est refusé.
Les deux branches dans un même body
Erreur de validation sur providers ou account_id. CorrectionUne première connexion prend providers et aucun account_id ; une reconnexion prend account_id et aucun providers. Envoyez une seule branche.
L'account ID n'arrive jamais
L'utilisateur a fermé l'onglet avant la redirection. CorrectionLa redirection est un confort. La source de vérité est l'événement account.add reçu sur votre endpoint webhook, qui porte le même state. Enregistrez à partir de l'événement, confirmez avec la redirection.
6000+ Les entreprises qui innovent avec Unipile
Des entreprises leaders nous font confiance
1 API
Toutes les plateformes centralisées en une API
2 jours
Intégration très rapide
30%
Réduction des efforts et des ressources de maintenance

Sécurité et conformité

Une protection de niveau entreprise pour vos données et workflows En savoir plus sur notre sécurité
SOC 2 Type II
SOC 2 Type II
Certifié
Contrôles de sécurité vérifiés de manière indépendante garantissant la protection des données et l'intégrité opérationnelle.
GDPR
GDPR
Conforme à la loi
Conformité totale avec les réglementations européennes en matière de protection des données pour le respect de la vie privée des utilisateurs.
99.9%
Temps de disponibilité de la plateforme au cours des 24 derniers mois
24/7
Support mondial avec API performante

FAQ Hosted Auth

Ce qu'est Hosted Auth, quel endpoint crée le lien, comment savoir que l'utilisateur a terminé, comment reconnecter, et quels providers l'assistant peut afficher.
Une page hébergée par Unipile sur laquelle votre utilisateur s'authentifie auprès de son provider. Vous créez un lien avec POST /v2/auth/link, vous y redirigez l'utilisateur et vous récupérez un account_id. Identifiants et tokens ne transitent jamais par votre code.
POST https://api.unipile.com/v2/auth/link, avec l'en-tête X-API-KEY et un body contenant providers, expires_on et redirect_uri. Il n'existe pas de chemin /v2/hosted/accounts/link en v2.
Par deux canaux. Le redirect_uri reçoit account_id, provider et state en paramètres de query string. L'événement webhook account.add porte le même state. Utilisez le webhook comme source de vérité et la redirection pour l'expérience utilisateur.
Même endpoint, avec account_id au lieu de providers. Le contrat indique que tout le compte est rafraîchi et que tous les produits configurés redémarrent. Déclenchez le parcours à partir de l'événement account.status.disconnected ou du statut du compte.
providers accepte *, un filtre par famille comme *:EMAILS, *:MESSAGING, *:CALENDAR ou *:SOCIAL, ou une liste parmi linkedin, whatsapp, google, outlook, imap, telegram et instagram. Utilisez mock pour tester le parcours.