BR
Unipile MCP · Hosted Auth

Unipile Hosted Auth, implementado pelo seu agente de código

Seus usuários conectam a própria conta de LinkedIn, WhatsApp ou e-mail em uma página hospedada pela Unipile, e seu app recebe um account ID. Com o Servidor MCP da Unipile, seu agente escreve a rota, o callback e o armazenamento, e nenhuma senha ou token chega ao seu código.
Teste grátis de 7 dias, sem cartão de crédito.
Seu agente · crm-app
Unipile MCP conectado
Sarah
Implemente o Unipile Hosted Auth neste app React e Fastify.
Ler endpointPOST /v2/auth/linkschema carregado
Adicionei a rota de link e o callback. O ID da conta fica salvo no workspace.
4 arquivos alterados · testado com providers: "mock"
Descreva o próximo recurso…
Caso de uso

Deixe seus usuários conectarem as próprias contas

Permitir que cada usuário do seu produto conecte as próprias contas, sem que seu código veja uma senha ou um token, e receber de volta o ID de conta que toda requisição posterior exige. Cada provedor tem seu próprio login, sua etapa de dois fatores e sua tela de consentimento. O Hosted Auth coloca tudo isso em uma página servida pela Unipile, e o agente conecta as três peças que ficam no seu app.
Sem isso Formulários de login, tokens, particularidades de cada provedor
Você cria um formulário de login por provedor e guarda tokens que nunca quis ter.
Prompts de dois fatores e telas de consentimento quebram o fluxo de um jeito diferente em cada provedor.
O ID de conta acaba sendo adivinhado a partir do redirect e se perde quando o usuário fecha a aba.
Com o servidor MCP da Unipile O resultado na sua aplicação
Um botão Conectar que abre o assistente hospedado e uma rota de callback que armazena o ID de conta no workspace.
Um botão Reconectar que reutiliza o mesmo endpoint com o ID de conta já armazenado.
O fluxo validado com o provedor mock na sua aplicação Development antes de vincular uma conta real.
Prompt, etapas, código

Entregue o prompt ao seu agente

Dois prompts, cada um com os endpoints Unipile que o agente lê e executa e o que chega ao seu projeto. Os paths estão completos, sobre a URL base da API https://api.unipile.com, com sua chave com escopo no X-API-KEY como header.
Seu agente · crm-appAplicação Development
Implemente o Unipile Hosted Auth nesta aplicação React e Fastify: uma rota de servidor que cria o link de autenticação, uma rota de callback que lê account_id e state, e a persistência do account_id no workspace atual.
Ler endpointPOST /v2/auth/linkschema carregado
Executar requisiçãoPOST /v2/auth/link201 · link
Adicionei POST /api/accounts/connect no Fastify: ele chama o endpoint do link de autenticação com providers, um expires_on quinze minutos à frente em ISO 8601 UTC, o redirect_uri do callback e um state assinado com o ID do workspace. A página de configurações em React abre o link. GET /auth/callback retornado, lê account_id, provider e state da query e armazena a conta. Testado com providers: "mock" na aplicação Development.4 arquivos alterados · fluxo de conexão testado de ponta a ponta

Um link criado no servidor, um callback que armazena o ID de conta

O link é criado no seu servidor com sua chave com escopo; o navegador recebe apenas a URL hospedada. Quando o usuário termina, a Unipile redireciona para o seu redirect_uri com account_id, provider e o seu state na query string. O agente lê esses três campos no contrato, não de memória, e escreve o callback de acordo.
Endpoints usados pelo agente
POST/v2/auth/linkGET/v2/accounts/{account_id}GET/v2/accounts/
Erro comum: Criar o link de autenticação pelo navegador. A chave vazaria; o frontend só abre o link que seu servidor devolve.
Referência do link de autenticação
Seu agente · crm-appAplicação Development
Adicione um botão Reconectar ao lado de cada conta conectada: chame o endpoint de link de autenticação da Unipile em modo de reautenticação com o account_id armazenado e trate o callback do mesmo jeito que na primeira conexão.
Ler endpointPOST /v2/auth/linkbranch de reautenticação
Executar requisiçãoGET /v2/accounts/{account_id}status: disconnected
Adicionei POST /api/accounts/:id/reconnect: mesmo endpoint, mesmo redirect_uri, mas o body carrega account_id em vez de providers. A página de configurações mostra o botão quando o status da conta não é running, e o callback existente trata o retorno. Verificado desconectando a conta mock na aplicação Development.2 arquivos alterados · reaproveita o callback da primeira conexão

Mesmo endpoint, muda um campo

Um link de reconexão leva account_id e nenhum providers; uma primeira conexão leva providers e nenhum account_id. O contrato diz que a conta inteira é atualizada e que todos os produtos configurados reiniciam, então o agente dispara isso a partir do status da conta e mantém um só callback para os dois fluxos.
Endpoints usados pelo agente
POST/v2/auth/linkGET/v2/accounts/{account_id}POST/v2/auth/checkpoint
Erro comum: Enviar providers e account_id juntos. O body é uma branch ou a outra, nunca as duas.
Dispare a partir de account.status.disconnected
Payload

O body da requisição, as duas branches e a resposta

Extraído literalmente do contrato v2 que o agente lê pelo servidor. Três campos são obrigatórios na primeira conexão, e a resposta é um único link.
1Vincular uma nova contaproviders, expires_on e redirect_uri são obrigatórios. state volta no redirect e no evento account.add. account_scope_id atribui a conta a um 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 uma conta existenteaccount_id substitui providers. A conta inteira é atualizada e todos os produtos configurados reiniciam.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" }
3Resposta e retornoA resposta é um HostedAuthLink. Depois do assistente, o redirect carrega account_id, provider e state; o webhook account.add carrega o mesmo state.{ "object": "HostedAuthLink", "link": "https://auth.unipile.com/…" } GET https://app.example.com/auth/callback?account_id=acc_…&provider=linkedin&state=ws_42.signed
Do Development para a Production

Teste primeiro em uma aplicação Development

Seu dashboard Unipile separa uma aplicação Development da Production. Dê ao agente uma chave com escopo de Development e use o provedor mock: o fluxo inteiro, sem nenhuma conta real.
1Rode o fluxo com providers: "mock"Link criado no servidor, callback lido, ID de conta armazenado.
2Reconecte a conta de testeDesconecte, abra o link de reconexão, status de volta em running.
3Confirme o account.add e então troque a chaveO webhook carrega o mesmo state do redirect; só então use a Production.
crm-app · DevelopmentUsada pelo seu agente
Escopodev-tests · 2 contas
Chavescoped Account API key
ContasConta de teste LinkedIn, caixa de e-mail Gmail de teste
Webhooks1 endpoint · eventos de mensagem
crm-app · ProductionSem alterações
Escopouma por workspace
Chavescoped keys, in your backend only
Contasas próprias contas dos seus usuários, via Hosted Auth
Solução de problemas

Erros comuns e o que eles significam

Os quatro erros que travam uma integração Hosted Auth e a correção de cada um. A maioria vem de copiar um exemplo da v1.
notify_url ou success_redirect_url no body
A requisição é rejeitada, ou o callback nunca dispara. CorreçãoEsses são campos da v1. O body da v2 aceita redirect_uri e state; as notificações passam por um endpoint de webhook inscrito em account.add e account.reconnect.
expires_on rejeitado
Erro de validação na data. CorreçãoO campo espera um datetime ISO 8601 UTC, YYYY-MM-DDTHH:MM:SS.sssZ. Um timestamp Unix ou uma data local é recusado.
As duas branches em um único body
Erro de validação em providers ou account_id. CorreçãoUma primeira conexão leva providers e nenhum account_id; uma reconexão leva account_id e nenhum providers. Envie uma branch só.
O ID de conta nunca chega
O usuário fechou a aba antes do redirect. CorreçãoO redirect é uma conveniência. A fonte de verdade é o evento account.add no seu endpoint de webhook, que carrega o mesmo state. Armazene a partir do evento, confirme pelo redirect.
6000+ Empresas que inovam com a Unipile
Com a confiança dos líderes do setor
1 API
Simplificar as operações de todos os principais canais de comunicação
2 dias
Obtenha integração ao vivo rapidamente com o mínimo de configuração
30%
Redução dos esforços e recursos de manutenção

Segurança e conformidade incorporadas

Proteção de nível empresarial para seus dados e fluxos de trabalho Saiba mais sobre nossa segurança
SOC 2 Tipo II
SOC 2 Tipo II
Certificado
Controles de segurança auditados de forma independente, garantindo a proteção dos dados e a integridade operacional.
GDPR
GDPR
Em conformidade
Conformidade total com os regulamentos europeus de proteção de dados para a privacidade do usuário.
99.9%
Tempo de atividade da plataforma nos últimos 24 meses
24/7
Suporte global com API de alto desempenho

FAQ do Hosted Auth

O que é o Hosted Auth, qual endpoint cria o link, como saber que o usuário terminou, como reconectar e quais provedores o assistente pode exibir.
Uma página hospedada pela Unipile onde seu usuário se autentica com o provedor dele. Você cria um link com POST /v2/auth/link, redireciona o usuário para lá e recebe de volta um account_id. Credenciais e tokens nunca passam pelo seu código.
POST https://api.unipile.com/v2/auth/link, com o header X-API-KEY e um body carregando providers, expires_on e redirect_uri. Não existe path /v2/hosted/accounts/link na v2.
Dois canais. O redirect_uri recebe account_id, provider e state como parâmetros de query. O evento de webhook account.add carrega o mesmo state. Use o webhook como fonte de verdade e o redirect para a experiência do usuário.
Mesmo endpoint, com account_id em vez de providers. O contrato diz que a conta inteira é atualizada e que todos os produtos configurados reiniciam. Dispare o fluxo a partir do evento account.status.disconnected ou do status da conta.
providers aceita *, um filtro de família como *:EMAILS, *:MESSAGING, *:CALENDAR ou *:SOCIAL, ou uma lista entre linkedin, whatsapp, google, outlook, imap, telegram, instagram e facebook. Use mock para testar o fluxo.