Unipile MCP · Hosted Auth

Unipile Hosted Auth, implementiert von Ihrem Coding-Agenten

Q: Welcher Endpoint erstellt den Hosted-Auth-Link?

POST https://api.unipile.com/v2/auth/link, mit dem X-API-KEY Header und einem Body mit providers, expires_on und redirect_uri. Einen Pfad /v2/hosted/accounts/link gibt es in v2 nicht. 03

Q: Woran erkenne ich, dass ein Nutzer die Verbindung abgeschlossen hat?

Zwei Kanäle. Die redirect_uri erhält account_id, provider und state als Query-Parameter. Das Webhook-Event account.add trägt denselben state. Nutzen Sie den Webhook als verlässliche Quelle und den Redirect für die Nutzerführung. 04

Q: Wie verbinde ich ein Konto neu, das nicht mehr funktioniert?

Derselbe Endpoint, mit account_id statt providers. Laut Vertrag wird das gesamte Konto aktualisiert und alle konfigurierten Produkte starten neu. Lösen Sie den Flow über das Event account.status.disconnected oder über den Kontostatus aus. 05

Q: Welche Anbieter kann ich im Wizard zeigen?

providers akzeptiert *, einen Familienfilter wie *:EMAILS, *:MESSAGING, *:CALENDAR oder *:SOCIAL, oder eine Liste aus linkedin, whatsapp, google, outlook, imap, telegram und instagram. Nutzen Sie mock, um den Flow zu testen. (function () { var root = document.getElementById('unipile-mcp-ha-faq'); if (!root) return; var buttons = root.querySelectorAll('.umhaf-q'); for (var i = 0; i

Ihre Nutzer verbinden ihr eigenes LinkedIn-, WhatsApp- oder E-Mail-Konto auf einer von Unipile gehosteten Seite. Mit dem Unipile MCP-Serverschreibt Ihr Agent die Route und den Callback.

Hosted Auth mit einem Agenten implementieren Hosted-Auth-Doku

7 Tage kostenlos testen, ohne Kreditkarte.

Implementiere Unipile Hosted Auth in dieser React- und Fastify-App.

Endpoint lesenPOST /v2/auth/linkSchema geladen

Link-Route und Callback ergänzt. Die Konto-ID wird am Workspace gespeichert.

4 Dateien geändert · getestet mit providers: "mock"

Nächstes Feature beschreiben…

Die Aufgabe

Was Sie erreichen wollen

Jeder Nutzer Ihres Produkts verbindet seine eigenen Konten, ohne dass Ihr Code je ein Passwort oder ein Token sieht, und Sie erhalten die Konto-ID zurück, die jede spätere Anfrage braucht. Jeder Anbieter hat seinen eigenen Login, seinen Zwei-Faktor-Schritt und seinen Zustimmungsdialog. Hosted Auth legt all das auf eine Seite, die Unipile ausliefert, und der Agent verkabelt die drei Teile, die Ihrer App gehören.

Ohne Login-Formulare, Tokens, Anbieter-Eigenheiten

Sie bauen pro Anbieter ein Login-Formular und speichern Tokens, die Sie gar nicht halten wollten.

Zwei-Faktor-Abfragen und Zustimmungsdialoge brechen den Flow bei jedem Anbieter anders.

Die Konto-ID wird am Ende aus dem Redirect erraten und geht verloren, sobald der Nutzer den Tab schließt.

Mit dem Unipile MCP-Server Das Ergebnis in Ihrer Anwendung

Ein Connect-Button, der den gehosteten Wizard öffnet, und eine Callback-Route, die die Konto-ID am Workspace speichert.

Ein Reconnect-Button, der denselben Endpoint mit der gespeicherten Konto-ID nutzt.

Der Flow, mit dem Mock-Anbieter in Ihrer Development-Anwendung validiert, bevor ein echtes Konto verbunden wird.

Prompt, Schritte, Code

Geben Sie Ihrem Agenten den Prompt

Zwei Prompts, jeweils mit den Unipile-Endpoints, die der Agent liest und aufruft, und dem, was in Ihrem Projekt landet. Die Pfade sind vollständig, auf der API-Basis-URL https://api.unipile.com, mit Ihrem Scoped Key im X-API-KEY Header.

Ihr Agent · crm-appDevelopment-App

Implementiere Unipile Hosted Auth in dieser React- und Fastify-Anwendung: eine Server-Route, die den Auth-Link erstellt, eine Callback-Route, die account_id und state liest, und die Speicherung der account_id am aktuellen Workspace.

Endpoint lesenPOST /v2/auth/linkSchema geladen

Anfrage ausführenPOST /v2/auth/link201 · link

Ergänzt POST /api/accounts/connect in Fastify: ruft den Auth-Link-Endpoint auf, mit providers, einem expires_on fünfzehn Minuten in der Zukunft in ISO 8601 UTC, der redirect_uri des Callbacks und einem signierten state mit der Workspace-ID. Die React-Settings-Seite öffnet den zurückgegebenen link. GET /auth/callback liest account_id, provider und state aus der Query und speichert das Konto. Getestet mit providers: "mock" in der Development-App.4 Dateien geändert · Connect-Flow end-to-end getestet

Ein serverseitig erstellter Link, ein Callback, der die Konto-ID speichert

Der Link wird auf Ihrem Server mit Ihrem Scoped Key erstellt; der Browser erhält nur die gehostete URL. Ist der Nutzer fertig, leitet Unipile auf Ihre redirect_uri ein, mit account_id, provider und Ihrem state im Query-String. Der Agent liest diese drei Felder aus dem Vertrag statt aus dem Gedächtnis und schreibt den Callback entsprechend.

Endpoints, die der Agent nutzt

POST/v2/auth/linkGET/v2/accounts/{account_id}GET/v2/accounts/

Häufiger Fehler: Den Auth-Link im Browser erstellen. Der Key würde nach außen gelangen; das Frontend öffnet nur den Link, den Ihr Server zurückgibt.

Referenz zum Auth-Link

Ihr Agent · crm-appDevelopment-App

Ergänze neben jedem verbundenen Konto einen Reconnect-Button: Rufe den Unipile-Auth-Link-Endpoint im Re-Authentifizierungs-Modus mit der gespeicherten account_id auf und verarbeite den Callback genauso wie bei der ersten Verbindung.

Endpoint lesenPOST /v2/auth/linkRe-Authentifizierungs-Zweig

Anfrage ausführenGET /v2/accounts/{account_id}status: disconnected

Ergänzt POST /api/accounts/:id/reconnect: derselbe Endpoint, dieselbe redirect_uri, aber der Body trägt account_id statt providers. Die Settings-Seite zeigt den Button, sobald der Kontostatus nicht running ist, und der bestehende Callback verarbeitet die Rückkehr. Verifiziert, indem das Mock-Konto in der Development-App getrennt wurde.2 Dateien geändert · nutzt den Callback der ersten Verbindung

Derselbe Endpoint, ein Feld ändert sich

Ein Reconnect-Link nimmt account_id und kein providers; eine Erstverbindung nimmt providers und kein account_id. Laut Vertrag wird das gesamte Konto aktualisiert und jedes konfigurierte Produkt startet neu, deshalb löst der Agent den Flow über den Kontostatus aus und behält einen Callback für beide Abläufe.

Endpoints, die der Agent nutzt

POST/v2/auth/linkGET/v2/accounts/{account_id}POST/v2/auth/checkpoint

Häufiger Fehler: providers und account_id zusammen senden. Der Body enthält den einen oder den anderen Zweig, nie beide.

Über account.status.disconnected auslösen

Payload

Der Request-Body, beide Zweige und die Response

Wörtlich aus dem v2-Vertrag, den der Agent über den Server liest. Für eine erste Verbindung sind drei Felder Pflicht, und die Response ist ein einzelner Link.

1Ein neues Konto verbindenproviders, expires_on und redirect_uri sind Pflicht. state wird im Redirect und im account.add-Event zurückgegeben. account_scope_id ordnet das Konto einem Scope zu.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_…" }

2Ein bestehendes Konto neu authentifizierenaccount_id ersetzt providers. Das gesamte Konto wird aktualisiert und jedes konfigurierte Produkt startet neu.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" }

3Response und RückkehrDie Response ist ein HostedAuthLink. Nach dem Wizard trägt der Redirect account_id, provider und state; der account.add-Webhook trägt denselben state.{ "object": "HostedAuthLink", "link": "https://auth.unipile.com/…" } GET https://app.example.com/auth/callback?account_id=acc_…&provider=linkedin&state=ws_42.signed

Von Development zu Production

Zuerst in einer Development-Anwendung testen

Ihr Unipile-Dashboard trennt eine Development-Anwendung von Production. Geben Sie dem Agenten einen Scoped Key aus Development und nutzen Sie den Mock-Anbieter: der komplette Flow, ohne echtes Konto.

1Den Flow mit providers: "mock" durchlaufenLink serverseitig erstellt, Callback gelesen, Konto-ID gespeichert.

2Das Testkonto neu verbindenTrennen, den Reconnect-Link öffnen, Status zurück auf running.

3account.add bestätigen, dann den Key wechselnDer Webhook trägt denselben state wie der Redirect; erst dann Production nutzen.

crm-app · DevelopmentVon Ihrem Agenten genutzt

Scopedev-tests · 2 Konten

Keyscoped Account API key

KontenLinkedIn-Testkonto, Gmail-Testpostfach

Webhooks1 Endpoint · Message-Events

crm-app · ProductionUnberührt

Scopeeiner pro Workspace

Keyscoped keys, in your backend only

Kontendie eigenen Konten Ihrer Nutzer, über Hosted Auth

Fehlerbehebung

Häufige Fehler und was sie bedeuten

Die vier Fehler, die eine Hosted-Auth-Integration stoppen, und die jeweilige Lösung. Die meisten stammen aus kopierten v1-Beispielen.

notify_url oder success_redirect_url im Body

Die Anfrage wird abgelehnt, oder der Callback feuert nie. LösungDas sind v1-Felder. Der v2-Body nimmt redirect_uri und state; Benachrichtigungen laufen über einen Webhook-Endpoint, der account.add und account.reconnect.

expires_on wird abgelehnt

Validierungsfehler beim Datum. LösungDas Feld erwartet ein ISO-8601-Datum in UTC, YYYY-MM-DDTHH:MM:SS.sssZ. Ein Unix-Timestamp oder ein lokales Datum wird abgelehnt.

Beide Zweige in einem Body

Validierungsfehler bei providers oder account_id. LösungEine Erstverbindung nimmt providers und kein account_id; ein Reconnect nimmt account_id und kein providers. Senden Sie einen Zweig.

Die Konto-ID kommt nie an

Der Nutzer hat den Tab vor dem Redirect geschlossen. LösungDer Redirect ist Komfort. Die verlässliche Quelle ist das account.add Event an Ihrem Webhook-Endpoint, das denselben stateträgt. Speichern Sie aus dem Event, bestätigen Sie über den Redirect.

6000+ Unternehmen, die mit Unipile innovieren

Vertrauen bei Branchenführern

1 API

Rationalisierung der Abläufe für alle wichtigen Kommunikationskanäle

2 Tage

Schnelle Live-Integration mit minimaler Einrichtung

30%

Verringerung des Wartungsaufwands und der Ressourcen

Integrierte Sicherheit und Compliance

Unternehmensgerechter Schutz für Ihre Daten und Arbeitsabläufe Erfahren Sie mehr über unsere Sicherheit

SOC 2 Typ II

Zertifiziert

Unabhängig geprüfte Sicherheitskontrollen zur Gewährleistung des Datenschutzes und der betrieblichen Integrität.

GDPR

Konform

Vollständige Einhaltung der europäischen Datenschutzbestimmungen zum Schutz der Privatsphäre der Nutzer.

99.9%

Betriebszeit der Plattform in den letzten 24 Monaten

24/7

Globaler Support mit leistungsstarker API

FAQ zu Hosted Auth

Was Hosted Auth ist, welcher Endpoint den Link erstellt, woran Sie erkennen, dass der Nutzer fertig ist, wie Sie neu verbinden und welche Anbieter der Wizard zeigen kann.

Eine von Unipile gehostete Seite, auf der sich Ihr Nutzer bei seinem Anbieter authentifiziert. Sie erstellen einen Link mit POST /v2/auth/link, leiten den Nutzer dorthin weiter und erhalten eine account_idzurück. Zugangsdaten und Tokens laufen nie durch Ihren Code.

POST https://api.unipile.com/v2/auth/link, mit dem X-API-KEY Header und einem Body mit providers, expires_on und redirect_uri. Einen Pfad /v2/hosted/accounts/link gibt es in v2 nicht.

Zwei Kanäle. Die redirect_uri erhält account_id, provider und state als Query-Parameter. Das Webhook-Event account.add trägt denselben state. Nutzen Sie den Webhook als verlässliche Quelle und den Redirect für die Nutzerführung.

Derselbe Endpoint, mit account_id statt providers. Laut Vertrag wird das gesamte Konto aktualisiert und alle konfigurierten Produkte starten neu. Lösen Sie den Flow über das Event account.status.disconnected oder über den Kontostatus aus.

providers akzeptiert *, einen Familienfilter wie *:EMAILS, *:MESSAGING, *:CALENDAR oder *:SOCIAL, oder eine Liste aus linkedin, whatsapp, google, outlook, imap, telegram und instagram. Nutzen Sie mock , um den Flow zu testen.