OAuth2 dla aplikacji zewnętrznych

Tylko dla aplikacji instalowanych przez innych klientów WASync. Authorization Code z PKCE, rotujące refresh tokeny i jedno ograniczenie strukturalne.

Pomiń ten rozdział, jeśli automatyzują Państwo własne konto

API key pozwala zrobić wszystko, co opisano w tej dokumentacji, bez dodatkowej infrastruktury. OAuth jest właściwym narzędziem tylko w jednym przypadku: Państwa aplikacja jest instalowana przez innych klientów WASync, a ci klienci muszą wyrazić zgodę na połączenia, których są właścicielami.

Rejestracja aplikacji

Aplikację rejestrują Państwo pod adresem https://developers.wasync.app/apps. Otrzymają Państwo client_id oraz client_secret (wyświetlany tylko raz). Należy też ustawić jeden lub więcej redirect_uri (porównywanych dokładnie przy wymianie tokenu), opcjonalny webhook_url oraz potrzebne zakresy (scopes).

Przebieg autoryzacji

Authorization Code z PKCE — wymagany jest S256. Przekierowują Państwo użytkownika na /oauth/authorize z parametrami response_type=code, client_id, redirect_uri, scope, state i 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`

Te adresy — podobnie jak adres serwera MCP — celowo zawierają cloudapi.wasync.app. To identyfikatory protokołu, które Państwa biblioteka kliencka i nasze dokumenty discovery mają już zarejestrowane, dlatego muszą zgadzać się co do bajta. Tylko bazowy adres REST i strony przeznaczone dla ludzi używają kanonicznej domeny developers.wasync.app.

Bitrix24. WASync wyświetla krótki kod użytkownika. Osoba z uprawnieniem zapisu do obszaru API & Agents portalu wpisuje go w Settings → API & Agents, wybierając połączenia i zakresy. Dostęp ten ma każdy administrator Bitrix24, a także każdy, komu administrator przyznał go w macierzy dostępu na stronie Staff.

Standalone. Deweloper zatwierdza dostęp pod adresem https://developers.wasync.app/authorize — automatycznie, jeśli jest właścicielem dokładnie jednej przestrzeni roboczej z co najmniej jednym połączeniem.

Wymiana kodu

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

access_token jest ważny 15 minut. refresh_token jest ważny 30 dni i rotuje przy każdym użyciu — nowy token należy zapisać atomowo, a odświeżanie serializować między procesami roboczymi. W przeciwnym razie dwa współbieżne procesy unieważnią nawzajem swoje tokeny.

Access token przekazuje się w tym samym nagłówku co API key: Authorization: Bearer …. Oba typy poświadczeń działają we wszystkich endpointach.

Jedno ograniczenie strukturalne

Uprawnienie (grant) jest wydawane wyłącznie dla połączeń, które już istnieją, dlatego integracja oparta tylko na OAuth nie może utworzyć pierwszego połączenia przestrzeni roboczej. API key może — dlatego szybki start zaczyna się właśnie od niego.

Webhooks dla aplikacji OAuth

Aplikacja OAuth ustawia webhook_url w samej aplikacji, zamiast wywoływać PUT /webhook. Uprawnienie musi zostać zatwierdzone z whatsapp.events, w przeciwnym razie nic nie zostanie dostarczone. Cała reszta — schemat podpisu, zasady ponawiania i payloady — jest identyczna jak w przewodniku po Webhooks.

Subskrypcje utworzone przed 24 lipca 2026 otrzymują tylko message.received, a te utworzone przed 10 sierpnia 2026 nie otrzymują zdarzeń połączeń. Aby otrzymywać nowsze typy zdarzeń, należy ponownie autoryzować aplikację albo napisać do wsparcia z prośbą o ich dodanie do istniejącej subskrypcji.

Czy ta strona była pomocna?