OAuth2 para apps de terceiros

Somente para apps que outros clientes da WASync instalam. Authorization Code com PKCE, refresh tokens rotativos e um limite estrutural.

Pule esta página se você automatiza a sua própria conta

Uma API key faz tudo o que está nesta documentação, sem nenhuma dessas engrenagens. O OAuth é a ferramenta certa para um único caso: o seu app é instalado por outros clientes da WASync, e esses clientes precisam autorizar o acesso a conexões que são deles.

Registre o app

Faça o registro em https://developers.wasync.app/apps. Você recebe um client_id e um client_secret (exibido uma única vez) e define um ou mais redirect_uri (comparados literalmente na troca do token), um webhook_url opcional e os escopos de que precisa.

O fluxo

Authorization Code com PKCE — S256 é obrigatório. Envie o usuário para /oauth/authorize com response_type=code, o seu client_id, redirect_uri, scope, um state e um code_challenge.

Endpoint	URL
Authorize	`https://cloudapi.wasync.app/oauth/authorize`
Token (`client_secret_post`)	`https://cloudapi.wasync.app/oauth/token`
Discovery	`https://cloudapi.wasync.app/.well-known/oauth-authorization-server`

Estas URLs — e a URL do servidor MCP — usam cloudapi.wasync.app de propósito. São identificadores de protocolo que a sua biblioteca cliente e os nossos documentos de discovery já registraram, então precisam coincidir byte a byte. Somente a URL base da REST e as páginas voltadas para pessoas usam o domínio canônico developers.wasync.app.

Bitrix24. A WASync mostra um código curto ao usuário, e alguém com acesso de escrita à área API & Agents do portal o informa em Settings → API & Agents, escolhendo as conexões e os escopos. Todo administrador do Bitrix24 tem esse acesso; o mesmo vale para quem recebeu a permissão de um administrador na matriz de acesso da página Staff.

Standalone. A pessoa desenvolvedora aprova em https://developers.wasync.app/authorize — a aprovação é automática quando ela é dona de exatamente um workspace com pelo menos uma conexão.

Troque o código

Token exchange

curl -X POST https://cloudapi.wasync.app/oauth/token \
  -d grant_type=authorization_code \
  -d code=$AUTH_CODE \
  -d redirect_uri=https://your.app/callback \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET \
  -d code_verifier=$CODE_VERIFIER

O access_token vale por 15 minutos. O refresh_token vale por 30 dias e rotaciona a cada uso — grave o novo de forma atômica e serialize as renovações entre os workers, ou dois workers em disputa invalidarão o token um do outro.

O access token vai no mesmo cabeçalho de uma API key: Authorization: Bearer …. Os dois tipos de credencial alcançam todos os endpoints.

Um limite estrutural

Uma autorização só é emitida sobre conexões que já existem, então uma integração apenas com OAuth não consegue criar a primeira conexão de um workspace. Uma API key consegue — por isso o quickstart começa com uma.

Webhooks para apps OAuth

Um app OAuth define o webhook_url no próprio app, em vez de chamar PUT /webhook, e a autorização precisa ter sido aprovada com whatsapp.events, ou nada é entregue. Todo o resto — o esquema de assinatura, a política de novas tentativas, os payloads — é idêntico ao do guia de Webhooks.

As assinaturas criadas antes de 24 de julho de 2026 recebem apenas message.received; as criadas antes de 10 de agosto de 2026 não recebem os eventos de conexão. Autorize novamente para receber os tipos de evento mais novos, ou escreva para o suporte e peça que eles sejam adicionados à sua assinatura existente.

Esta página foi útil?