OAuth2 per app di terze parti

Solo per le app che altri clienti WASync installano. Authorization Code con PKCE, refresh token a rotazione e un limite strutturale.

Salti questa pagina se automatizza il suo account

Una API key fa tutto ciò che è descritto in questa documentazione, senza alcun meccanismo aggiuntivo. OAuth è lo strumento giusto per un solo caso: la sua app viene installata da altri clienti WASync, e questi clienti devono dare il consenso per connessioni che sono di loro proprietà.

Registrare l'app

Si registri su https://developers.wasync.app/apps. Riceverà un client_id e un client_secret (mostrato una sola volta), e potrà impostare uno o più redirect_uri (confrontati esattamente durante lo scambio del token), un webhook_url facoltativo e gli scope necessari.

Il flusso

Authorization Code con PKCE — S256 è obbligatorio. Indirizzi l'utente a /oauth/authorize con response_type=code, il suo client_id, redirect_uri, scope, uno state e un 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`

Questi URL — così come l'URL del server MCP — riportano volutamente cloudapi.wasync.app. Sono identificatori di protocollo che la libreria del suo client e i nostri documenti di discovery hanno già registrato, quindi devono coincidere byte per byte. Solo l'URL di base REST e le pagine destinate agli utenti usano il dominio canonico developers.wasync.app.

Bitrix24. WASync mostra un breve codice utente, e una persona con accesso in scrittura all'area API & Agents del portale lo inserisce in Settings → API & Agents, scegliendo connessioni e scope. Ogni amministratore Bitrix24 ha questo accesso, così come chiunque lo abbia ricevuto da un amministratore nella matrice di accesso della pagina Staff.

Standalone. Lo sviluppatore approva su https://developers.wasync.app/authorize — l'approvazione è automatica quando possiede esattamente un workspace con almeno una connessione.

Scambiare il codice

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

L'access_token dura 15 minuti. Il refresh_token dura 30 giorni e ruota a ogni utilizzo — salvi quello nuovo in modo atomico e serializzi gli aggiornamenti tra i worker, altrimenti due worker in competizione invalideranno a vicenda il proprio token.

L'access token va nello stesso header di una API key: Authorization: Bearer …. Entrambi i tipi di credenziale raggiungono ogni endpoint.

Un limite strutturale

Una concessione viene emessa solo su connessioni che esistono già, quindi un'integrazione solo OAuth non può creare la prima connessione di un workspace. Una API key può farlo — ed è per questo che il quickstart inizia con una.

Webhook per le app OAuth

Un'app OAuth imposta webhook_url sull'app stessa anziché chiamare PUT /webhook, e la concessione deve essere stata approvata con whatsapp.events altrimenti non viene consegnato nulla. Tutto il resto — lo schema di firma, la policy di retry, i payload — è identico alla guida ai webhook.

Le sottoscrizioni create prima del 24 luglio 2026 ricevono solo message.received; quelle create prima del 10 agosto 2026 non ricevono gli eventi di connessione. Riautorizzi per ricevere i tipi di evento più recenti, oppure scriva al supporto e ne chieda l'aggiunta alla sua sottoscrizione esistente.

Questa pagina è stata utile?