Unipile MCP · Hosted Auth

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

Q: Qual endpoint cria o link do Hosted Auth?

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. 03

Q: Como eu sei que um usuário terminou de conectar?

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. 04

Q: Como reconectar uma conta que parou de funcionar?

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. 05

Q: Quais provedores posso exibir no assistente?

providers aceita *, um filtro de família como *:EMAILS, *:MESSAGING, *:CALENDAR ou *:SOCIAL, ou uma lista entre linkedin, whatsapp, google, outlook, imap, telegram e instagram. Use mock para testar o fluxo. (function () { var root = document.getElementById('unipile-mcp-ha-faq'); if (!root) return; var buttons = root.querySelectorAll('.umhaf-q'); for (var i = 0; i

Seus usuários vinculam a própria conta de LinkedIn, WhatsApp ou e-mail em uma página hospedada pela Unipile. Com o Servidor MCP da Unipile, seu agente escreve a rota e o callback.

Implementar o Hosted Auth com um agente Docs do Hosted Auth

Teste grátis de 7 dias, sem cartão de crédito.

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…

O objetivo

O que você quer construir

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

Certificado

Controles de segurança auditados de forma independente, garantindo a proteção dos dados e a integridade operacional.

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 e instagram. Use mock para testar o fluxo.