Unipile MCP · Hosted Auth

Unipile Hosted Auth, implementato dal suo coding agent

Q: Quale endpoint crea il link Hosted Auth?

POST https://api.unipile.com/v2/auth/link, con l'header X-API-KEY e un body che contiene providers, expires_on e redirect_uri. Non esiste alcun percorso /v2/hosted/accounts/link nella v2.

Q: Come faccio a sapere che un utente ha completato la connessione?

Due canali. Il redirect_uri riceve account_id, provider e state come parametri di query. L'evento webhook account.add contiene lo stesso state. Usi il webhook come fonte di verità e il redirect per l'esperienza utente.

Q: Come riconnettere un account che ha smesso di funzionare?

Stesso endpoint, con account_id invece di providers. Il contratto indica che l'intero account viene aggiornato e che tutti i prodotti configurati ripartono. Avvii il flusso dall'evento account.status.disconnected o dallo stato dell'account.

Q: Quali provider posso mostrare nel wizard?

providers accetta *, un filtro per famiglia come *:EMAILS, *:MESSAGING, *:CALENDAR o *:SOCIAL, oppure un elenco tra linkedin, whatsapp, google, outlook, imap, telegram e instagram. Usi mock per testare il flusso.

I suoi utenti collegano il proprio account LinkedIn, WhatsApp o email su una pagina ospitata da Unipile. Con il Server MCP Unipile, il suo agente scrive la route e il callback.

Implementare Hosted Auth con un agente Documentazione Hosted Auth

Prova gratuita di 7 giorni, senza carta di credito.

Implementa Unipile Hosted Auth in questa app React e Fastify.

Lettura endpointPOST /v2/auth/linkschema caricato

Aggiunti la route del link e il callback. L'account ID viene salvato sul workspace.

4 file modificati · testato con providers: "mock"

Descriva la prossima funzionalità…

L'obiettivo

Che cosa si vuole ottenere

Permettere a ogni utente del suo prodotto di collegare i propri account, senza che il suo codice veda mai una password o un token, e ottenere l'account ID richiesto da ogni chiamata successiva. Ogni provider ha il proprio login, il proprio passaggio a due fattori e la propria schermata di consenso. Hosted Auth riunisce tutto questo in un'unica pagina servita da Unipile, e l'agente collega i tre pezzi di competenza della sua app.

Senza Form di login, token, particolarità dei provider

Si costruisce un form di login per ogni provider e si conservano token che non si voleva gestire.

Le richieste a due fattori e le schermate di consenso interrompono il flusso in modo diverso su ogni provider.

L'account ID finisce per essere dedotto dal redirect, e va perso quando l'utente chiude la scheda.

Con il server MCP di Unipile Il risultato nella sua applicazione

Un pulsante Connetti che apre il wizard ospitato, e una route di callback che salva l'account ID sul workspace.

Un pulsante Riconnetti che riusa lo stesso endpoint con l'account ID salvato.

Il flusso validato con il provider mock sulla sua applicazione Development, prima di collegare un account reale.

Prompt, passaggi, codice

Dia il prompt al suo agente

Due prompt, ciascuno con gli endpoint Unipile che l'agente legge ed esegue e ciò che arriva nel suo progetto. I percorsi sono completi, sull'URL di base dell'API https://api.unipile.com, con la sua chiave scoped passata nell'header X-API-KEY della richiesta.

Il suo agente · crm-appApp Development

Implementa Unipile Hosted Auth in questa applicazione React e Fastify: una route server che crea il link di autenticazione, una route di callback che legge account_id e state, e il salvataggio di account_id sul workspace corrente.

Lettura endpointPOST /v2/auth/linkschema caricato

Esecuzione richiestaPOST /v2/auth/link201 · link

Aggiunta POST /api/accounts/connect in Fastify: chiama l'endpoint del link di autenticazione con providers, un expires_on a quindici minuti, in ISO 8601 UTC, il redirect_uri del callback e uno state firmato che contiene l'ID del workspace. La pagina Settings in React apre l'URL restituito nel campo link. GET /auth/callback legge account_id, provider e state dalla query e salva l'account. Testato con providers: "mock" sull'app Development.4 file modificati · flusso di connessione testato end to end

Un link creato lato server, un callback che salva l'account ID

Il link si crea sul suo server con la sua chiave scoped; il browser riceve solo l'URL ospitato. Quando l'utente ha finito, Unipile reindirizza al suo redirect_uri con account_id, provider e il suo state nella query string. L'agente legge questi tre campi dal contratto, non dalla memoria, e scrive il callback di conseguenza.

Endpoint usati dall'agente

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

Errore comune: creare il link di autenticazione dal browser. La chiave verrebbe esposta; il frontend apre solo il link restituito dal suo server.

Riferimento del link di autenticazione

Il suo agente · crm-appApp Development

Aggiungi un pulsante Reconnect accanto a ogni account collegato: chiama l'endpoint del link di autenticazione Unipile in modalità di riautenticazione con l'account_id salvato, e gestisci il callback come per la prima connessione.

Lettura endpointPOST /v2/auth/linkramo di riautenticazione

Esecuzione richiestaGET /v2/accounts/{account_id}status: disconnected

Aggiunta POST /api/accounts/:id/reconnect: stesso endpoint, stesso redirect_uri, ma il body contiene account_id invece di providers. La pagina Settings mostra il pulsante quando lo stato dell'account non è running, e il callback esistente gestisce il ritorno. Verificato disconnettendo l'account mock sull'app Development.2 file modificati · riusa il callback della prima connessione

Stesso endpoint, cambia un solo campo

Un link di riconnessione accetta account_id e non providers; una prima connessione accetta providers e non account_id. Il contratto indica che l'intero account viene aggiornato e che ogni prodotto configurato riparte, quindi l'agente lo attiva a partire dallo stato dell'account e mantiene un solo callback per entrambi i flussi.

Endpoint usati dall'agente

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

Errore comune: inviare sia providers sia account_id. Il body segue un ramo o l'altro, mai entrambi.

Attivarlo da account.status.disconnected

Payload

Il body della richiesta, entrambi i rami e la risposta

Testuale dal contratto v2 che l'agente legge tramite il server. Per una prima connessione servono tre campi, e la risposta è un singolo link.

1Collegare un nuovo accountproviders, expires_on e redirect_uri sono obbligatori. state viene restituito nel redirect e nell'evento account.add. account_scope_id assegna l'account a uno 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_…" }

2Ri-autenticare un account esistenteaccount_id sostituisce providers. L'intero account viene aggiornato e ogni prodotto configurato riparte.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" }

3Risposta e ritornoLa risposta è un HostedAuthLink. Dopo il wizard, il redirect trasporta account_id, provider e state; il webhook account.add trasporta lo stesso state.{ "object": "HostedAuthLink", "link": "https://auth.unipile.com/…" } GET https://app.example.com/auth/callback?account_id=acc_…&provider=linkedin&state=ws_42.signed

Dallo sviluppo alla produzione

Testare prima su un'applicazione Development

La dashboard Unipile separa un' applicazione Development dalla Produzione. Basta fornire all'agente una chiave scoped di Development e usare il provider mock: il flusso completo, senza account reali.

1Eseguire il flusso con providers: "mock"Link creato lato server, callback letto, account ID salvato.

2Riconnettere l'account di testDisconnetterlo, aprire il link di riconnessione, stato di nuovo running.

3Verificare account.add, poi cambiare chiaveIl webhook trasporta lo stesso state del redirect; solo allora si passa alla Produzione.

crm-app · DevelopmentUsata dal suo agente

Scopedev-tests · 2 account

Chiavescoped Account API key

AccountAccount LinkedIn di test, casella Gmail di test

Webhooks1 endpoint · eventi message

crm-app · ProductionIntatta

Scopeuno per workspace

Chiavescoped keys, in your backend only

Accountgli account dei suoi utenti, tramite Hosted Auth

Troubleshooting

Errori frequenti e cosa significano

I quattro errori che bloccano un'integrazione Hosted Auth, e come risolverli. Quasi sempre nascono dalla copia di un esempio v1.

notify_url o success_redirect_url nel body

La richiesta viene rifiutata, oppure il callback non scatta mai. SoluzioneSono campi v1. Il body v2 accetta redirect_uri e state; le notifiche passano da un endpoint webhook sottoscritto a account.add e account.reconnect.

expires_on rifiutato

Errore di validazione sulla data. SoluzioneIl campo richiede un datetime ISO 8601 UTC, YYYY-MM-DDTHH:MM:SS.sssZ. Un timestamp Unix o una data locale vengono rifiutati.

Entrambi i rami nello stesso body

Errore di validazione su providers o account_id. SoluzioneUna prima connessione prende providers e non account_id; una riconnessione prende account_id e non providers. Inviare un solo ramo.

L'account ID non arriva mai

L'utente ha chiuso la scheda prima del redirect. SoluzioneIl redirect è solo una comodità. La fonte di verità è l'evento account.add sul suo endpoint webhook, che trasporta lo stesso state. Salvare dall'evento, confermare dal redirect.

6000+ Aziende che innovano con Unipile

Fiducia da parte dei leader del settore

1 API

Semplificare le operazioni per tutti i principali canali di comunicazione

2 giorni

Integrazione rapida con una configurazione minima

30%

Riduzione dell'impegno e delle risorse per la manutenzione

Sicurezza e conformità integrate

Protezione di livello aziendale per i vostri dati e flussi di lavoro Per saperne di più sulla nostra sicurezza

SOC 2 Tipo II

Certificato

Controlli di sicurezza verificati in modo indipendente che garantiscono la protezione dei dati e l'integrità operativa.

GDPR

Conforme

Piena conformità alle normative europee sulla protezione dei dati per la privacy degli utenti.

99.9%

Uptime della piattaforma negli ultimi 24 mesi

24/7

Supporto globale con API ad alte prestazioni

FAQ Hosted Auth

Che cos'è Hosted Auth, quale endpoint crea il link, come sapere che l'utente ha finito, come riconnettere e quali provider può mostrare il wizard.

Una pagina ospitata da Unipile in cui il suo utente si autentica presso il proprio provider. Lei crea un link con POST /v2/auth/link, vi reindirizza l'utente e riceve in cambio un account_id. Credenziali e token non passano mai dal suo codice.

POST https://api.unipile.com/v2/auth/link, con l'header X-API-KEY e un body che contiene providers, expires_on e redirect_uri. Non esiste alcun percorso /v2/hosted/accounts/link nella v2.

Due canali. Il redirect_uri riceve account_id, provider e state come parametri di query. L'evento webhook account.add contiene lo stesso state. Usi il webhook come fonte di verità e il redirect per l'esperienza utente.

Stesso endpoint, con account_id invece di providers. Il contratto indica che l'intero account viene aggiornato e che tutti i prodotti configurati ripartono. Avvii il flusso dall'evento account.status.disconnected o dallo stato dell'account.

providers accetta *, un filtro per famiglia come *:EMAILS, *:MESSAGING, *:CALENDAR o *:SOCIAL, oppure un elenco tra linkedin, whatsapp, google, outlook, imap, telegram e instagram. Usi mock per testare il flusso.