Nu bouwen
NL
Unipile MCP · Hosted Auth

Unipile Hosted Auth, geïmplementeerd door uw coding agent

Uw gebruikers koppelen hun eigen LinkedIn-, WhatsApp- of e-mailaccount op een pagina die Unipile host. Met de Unipile MCP-server schrijft uw agent de route en de callback.
Hosted Auth implementeren met een agent Hosted Auth-docs
7 dagen gratis proberen, geen creditcard nodig.
Uw agent · crm-app
Unipile MCP verbonden
Sarah
Implementeer Unipile Hosted Auth in deze React- en Fastify-app.
Endpoint lezenPOST /v2/auth/linkschema geladen
Link-route en callback toegevoegd. De account-ID wordt op de workspace opgeslagen.
4 bestanden gewijzigd · getest met providers: "mock"
Beschrijf de volgende feature…
De taak

Wat u wilt bereiken

Elke gebruiker van uw product zijn eigen accounts laten koppelen, zonder dat uw code ooit een wachtwoord of token ziet, en de account-ID terugkrijgen die elke latere request nodig heeft. Elke provider heeft een eigen login, tweestapsverificatie en toestemmingsscherm. Hosted Auth zet dat allemaal op één pagina die Unipile aanbiedt, en de agent koppelt de drie onderdelen die uw app zelf beheert.
Zonder Inlogformulieren, tokens, eigenaardigheden per provider
U bouwt een inlogformulier per provider en bewaart tokens die u liever niet in handen had.
Tweestapsverificatie en toestemmingsschermen breken de flow bij elke provider op een andere manier.
De account-ID wordt uit de redirect afgeleid en gaat verloren als de gebruiker het tabblad sluit.
Met de Unipile MCP-server Het resultaat in uw applicatie
Een Connect-knop die de gehoste wizard opent, en een callback-route die de account-ID op de workspace opslaat.
Een Reconnect-knop die hetzelfde endpoint hergebruikt met de opgeslagen account-ID.
De flow gevalideerd met de mock-provider op uw Development-applicatie voordat er een echt account wordt gekoppeld.
Prompt, stappen, code

Geef uw agent de prompt

Twee prompts, elk met de Unipile-endpoints die de agent leest en aanroept en wat er in uw project terechtkomt. Paden zijn volledig, op de API-basis-URL https://api.unipile.com, met uw scoped sleutel in de X-API-KEY header.
Uw agent · crm-appDevelopment-app
Implementeer Unipile Hosted Auth in deze React- en Fastify-applicatie: een serverroute die de auth-link aanmaakt, een callback-route die account_id en state leest, en opslag van de account_id op de huidige workspace.
Endpoint lezenPOST /v2/auth/linkschema geladen
Request uitvoerenPOST /v2/auth/link201 · link
Toegevoegd: POST /api/accounts/connect in Fastify: roept het auth link-endpoint aan met providers, een expires_on vijftien minuten vooruit in ISO 8601 UTC, de redirect_uri van de callback en een ondertekende state met de workspace-ID. De React-pagina Settings opent de geretourneerde link. GET /auth/callback leest account_id, provider en state uit de query en slaat het account op. Getest met providers: "mock" op de Development-app.4 bestanden gewijzigd · connect-flow end-to-end getest

Een link die server-side wordt aangemaakt, een callback die de account-ID opslaat

De link wordt op uw server aangemaakt met uw scoped sleutel; de browser ontvangt alleen de gehoste URL. Als de gebruiker klaar is, redirect Unipile naar uw redirect_uri met account_id, provider met de state in de query string. De agent leest deze drie velden uit het contract, niet uit het geheugen, en schrijft de callback daarop.
Endpoints die de agent gebruikt
POST/v2/auth/linkGET/v2/accounts/{account_id}GET/v2/accounts/
Veelgemaakte fout: De auth-link vanuit de browser aanmaken. De sleutel zou uitlekken; de frontend opent alleen de link die uw server teruggeeft.
Referentie auth link
Uw agent · crm-appDevelopment-app
Voeg naast elk gekoppeld account een Reconnect-knop toe: roep het Unipile auth link-endpoint aan in re-authenticatiemodus met de opgeslagen account_id, en verwerk de callback op dezelfde manier als bij de eerste koppeling.
Endpoint lezenPOST /v2/auth/linkre-authenticate-tak
Request uitvoerenGET /v2/accounts/{account_id}status: disconnected
Toegevoegd: POST /api/accounts/:id/reconnect: hetzelfde endpoint, dezelfde redirect_uri, maar de body bevat account_id in plaats van providers. De Settings-pagina toont de knop als de accountstatus niet running is, en de bestaande callback verwerkt de terugkeer. Geverifieerd door het mock-account op de Development-app te ontkoppelen.2 bestanden gewijzigd · hergebruikt de callback van de eerste koppeling

Hetzelfde endpoint, één veld verandert

Een reconnect-link krijgt account_id en geen providers; een eerste koppeling krijgt providers en geen account_id. Volgens het contract wordt het hele account ververst en start elk geconfigureerd product opnieuw, dus de agent triggert het vanuit de accountstatus en houdt één callback voor beide flows.
Endpoints die de agent gebruikt
POST/v2/auth/linkGET/v2/accounts/{account_id}POST/v2/auth/checkpoint
Veelgemaakte fout: Zowel providers als account_id meesturen. De body bevat de ene tak of de andere, nooit beide.
Trigger het vanuit account.status.disconnected
Payload

De request body, beide takken en de response

Letterlijk uit het v2-contract dat de agent via de server leest. Voor een eerste koppeling zijn drie velden verplicht, en de response is één link.
1Een nieuw account koppelenproviders, expires_on en redirect_uri zijn verplicht. state wordt teruggestuurd in de redirect en in het account.add-event. account_scope_id wijst het account toe aan een 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_…" }
2Een bestaand account opnieuw authenticerenaccount_id vervangt providers. Het hele account wordt ververst en elk geconfigureerd product start opnieuw.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 en terugkeerDe response is een HostedAuthLink. Na de wizard bevat de redirect account_id, provider en state; de account.add-webhook bevat dezelfde state.{ "object": "HostedAuthLink", "link": "https://auth.unipile.com/…" } GET https://app.example.com/auth/callback?account_id=acc_…&provider=linkedin&state=ws_42.signed
Van Development naar productie

Test eerst op een Development-applicatie

Uw Unipile-dashboard scheidt een Development-applicatie van Production. Geef de agent een scoped sleutel uit Development en gebruik de mock-provider: de hele flow, zonder echt account.
1Voer de flow uit met providers: "mock"Link server-side aangemaakt, callback gelezen, account-ID opgeslagen.
2Het testaccount opnieuw verbindenOntkoppel het, open de reconnect-link, status weer op running.
3Bevestig account.add en zet dan de sleutel omDe webhook bevat dezelfde state als de redirect; gebruik pas daarna Production.
crm-app · DevelopmentGebruikt door uw agent
Scopedev-tests · 2 accounts
Sleutelscoped Account API-sleutel
AccountsLinkedIn-testaccount, Gmail-testmailbox
Webhooks1 endpoint · berichtevents
crm-app · ProductionOnaangeroerd
Scopeéén per workspace
Sleutelscoped sleutels, alleen in uw backend
Accountsde eigen accounts van uw gebruikers, via Hosted Auth
Probleemoplossing

Veelvoorkomende fouten en wat ze betekenen

De vier fouten die een Hosted Auth-integratie tegenhouden, en de oplossing voor elk. De meeste komen voort uit het kopiëren van een v1-voorbeeld.
notify_url of success_redirect_url in de body
De request wordt geweigerd, of de callback wordt nooit aangeroepen. OplossingDit zijn v1-velden. De v2-body neemt redirect_uri en state; notificaties lopen via een webhook-endpoint met een abonnement op account.add en account.reconnect.
expires_on geweigerd
Validatiefout op de datum. OplossingHet veld verwacht een ISO 8601 UTC-datetime, YYYY-MM-DDTHH:MM:SS.sssZ. Een Unix-timestamp of een lokale datum wordt geweigerd.
Beide takken in één body
Validatiefout op providers of account_id. OplossingEen eerste koppeling neemt providers en geen account_id; een reconnect neemt account_id en geen providers. Stuur één tak mee.
De account-ID komt nooit aan
De gebruiker sloot het tabblad vóór de redirect. OplossingDe redirect is een gemak. De bron van waarheid is het account.add event op uw webhook-endpoint, dat dezelfde state bevat. Sla op vanuit het event, bevestig vanuit de redirect.
6000+ Bedrijven innoveren met Unipile
Vertrouwd door marktleiders
1 API
Activiteiten stroomlijnen voor alle belangrijke communicatiekanalen
2 dagen
Snel live integratie bereiken met minimale installatie
30%
Vermindering van onderhoudsinspanningen en -middelen

Ingebouwde beveiliging en compliance

Enterprise-bescherming voor uw gegevens en workflows Meer informatie over onze beveiliging
SOC 2 type II
SOC 2 type II
Gecertificeerd
Onafhankelijk gecontroleerde beveiligingscontroles voor gegevensbescherming en operationele integriteit.
GDPR
GDPR
Conform
Volledige naleving van de Europese regelgeving voor gegevensbescherming voor de privacy van gebruikers.
99.9%
Platform Uptime over de laatste 24 maanden
24/7
Wereldwijde ondersteuning met krachtige API

FAQ over Hosted Auth

Wat Hosted Auth is, welk endpoint de link aanmaakt, hoe u weet dat de gebruiker klaar is, hoe u opnieuw verbindt en welke providers de wizard kan tonen.
Een door Unipile gehoste pagina waar uw gebruiker zich bij zijn provider authenticeert. U maakt een link aan met POST /v2/auth/link, stuurt de gebruiker ernaartoe en krijgt een account_id terug. Inloggegevens en tokens gaan nooit door uw code.
POST https://api.unipile.com/v2/auth/link, met de X-API-KEY header en een body met providers, expires_on en redirect_uri. Er is geen /v2/hosted/accounts/link pad in v2.
Via twee kanalen. De redirect_uri ontvangt account_id, provider en state als queryparameters. Het account.add webhookevent bevat dezelfde state. Gebruik de webhook als bron van waarheid en de redirect voor de gebruikerservaring.
Hetzelfde endpoint, met account_id in plaats van providers. Volgens het contract wordt het hele account ververst en starten alle geconfigureerde producten opnieuw. Start de flow vanuit het account.status.disconnected event of vanuit de accountstatus.
providers accepteert *, een familiefilter zoals *:EMAILS, *:MESSAGING, *:CALENDAR of *:SOCIAL, of een lijst uit linkedin, whatsapp, google, outlook, imap, telegram en instagram. Gebruik mock om de flow te testen.