--- title: "Połącz za pomocą OAuth" description: "Autoryzuj klientów MCP i interfejs CLI ThunderPhone bez udostępniania klucza API." --- OAuth umożliwia aplikacji połączenie z jedną organizacją ThunderPhone z uprawnieniami, które zatwierdzisz. Klienci katalogowi powinni domyślnie używać OAuth. Klucze API organizacji pozostają dostępne dla klientów wymagających ręcznie skonfigurowanego tokenu Bearer. ## Zatwierdź połączenie Rozpocznij połączenie w kliencie MCP. Zaloguj się do ThunderPhone, sprawdź nazwę aplikacji i żądane uprawnienia, wybierz organizację, a następnie wybierz **Zatwierdź**. Wybierz **Odrzuć**, jeśli nie rozpoczęto połączenia przez Ciebie lub nie ufasz aplikacji. Nazwy aplikacji są podawane przez ich twórców i nie stanowią oznaki weryfikacji. Uprawnienia do odczytu udostępniają wskazane dane, w tym nagrania i transkrypcje, gdy żądane jest `calls:read`. Uprawnienia do zapisu mogą zmieniać lub usuwać zasoby; połączenia, kampanie, zakupy numerów telefonów i wdrożenia mogą generować koszty lub wpływać na środowisko produkcyjne. Rola w organizacji nadal obowiązuje. W przypadku połączenia CLI otwórz link weryfikacyjny wyświetlony w terminalu, porównaj ośmioznakowy kod, wybierz organizację i zatwierdź. Samo otwarcie linku nie przyznaje dostępu. Kody wygasają po 15 minutach. ## Odłącz aplikację W panelu otwórz **Organizacja → Klucze API → Autoryzowane aplikacje** i wybierz **Cofnij**. Spowoduje to cofnięcie wybranego upoważnienia dla bieżącej organizacji, w tym jej tokenów dostępu i odświeżania. Połącz się ponownie z poziomu aplikacji, jeśli chcesz ponownie ją autoryzować. ## Wykrywanie dla klientów MCP Użyj adresu URL serwera `https://api.thunderphone.com/v1/mcp`. Żądanie bez prawidłowego uwierzytelnienia otrzymuje `401` z: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Pobierz ten dokument, a następnie pobierz metadane serwera autoryzacji pod adresem `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Metadane zasobu są również dostępne pod adresem `/.well-known/oauth-protected-resource/v1/mcp`. Używaj zwróconych punktów końcowych zamiast konstruować je samodzielnie. Identyfikator zasobu to `https://api.thunderphone.com/v1/mcp`. Serwer obsługuje kod autoryzacyjny z **S256 PKCE**, rotujące tokeny odświeżania, publiczną dynamiczną rejestrację klientów, unieważnianie oraz mechanizm autoryzacji urządzeń. Nie ma sekretów klienta ani mechanizmów niejawnych. Wykrywanie OpenID jest również dostępne pod adresem `/.well-known/openid-configuration`; obejmuje te same pola serwera autoryzacji oraz `subject_types_supported: ["public"]` i punkt końcowy userinfo. Tokeny ID i dokumenty metadanych identyfikatora klienta (CIMD) nie są obsługiwane. ### Zarejestruj publicznego klienta Wyślij JSON do `POST /v1/oauth/register`: ```json { "client_name": "My MCP client", "redirect_uris": ["http://127.0.0.1:8765/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"] } ``` Zapisz zwrócony `client_id`. Przekierowania muszą używać HTTPS albo HTTP na `127.0.0.1` lub `localhost`. Zarejestruj dokładny identyfikator URI wywołania zwrotnego, łącznie z portem i ścieżką. Fragmenty i osadzone poświadczenia są odrzucane. Opcjonalne `client_uri` i `logo_uri` muszą używać HTTPS; ThunderPhone nie pobiera ich podczas rejestracji. Rejestracja jest ograniczana limitem żądań. Zarejestrowani klienci nie wygasają i pozostają zarejestrowani po unieważnieniu połączenia. Wywołania zwrotne HTTPS obejmują `https://chatgpt.com/connector/oauth/` oraz `https://chatgpt.com/connector_platform_oauth_redirect`. Każde połączenie może zarejestrować własnego klienta. ### Kod autoryzacyjny Otwórz wykryty punkt końcowy autoryzacji z parametrami `client_id`, dokładnie zarejestrowanym `redirect_uri`, `response_type=code`, losowym `state`, `scope`, `code_challenge`, `code_challenge_method=S256` oraz `resource=https://api.thunderphone.com/v1/mcp`. Oblicz wyzwanie jako skrót SHA-256 zakodowany w base64url bez dopełnienia, utworzony ze świeżego weryfikatora PKCE o wysokiej entropii. Sprawdź zwrócone `state` i `iss` przed wymianą kodu. Każda odpowiedź autoryzacji, w tym odmowa i błędy protokołu, identyfikuje wystawcę za pomocą `iss`, dokładnie zgodnego z wykrytym `issuer`. Błędy dotyczące nieprawidłowego klienta lub wywołania zwrotnego są zwracane lokalnie bez przekierowania do tego wywołania zwrotnego. Wymień kod pod adresem `POST /v1/oauth/token`, używając kodowania formularza (akceptowany jest również JSON): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` Opcjonalny parametr `resource` jest akceptowany zarówno w żądaniach autoryzacji, jak i tokenów, w tym przy odświeżaniu i wymianach urządzeń. Gdy jest pominięty, domyślnie używany jest wykryty zasób MCP. Gdy jest obecny, musi dokładnie odpowiadać temu zasobowi; inne wartości zwracają `invalid_target`. Tokeny dostępu zawierają tę grupę odbiorców, a MCP odrzuca tokeny z brakującą lub inną grupą odbiorców, zwracając `401` i wyzwanie wykrywania. Żądania autoryzacji i kody wygasają po 10 minutach. Każda odpowiedź tokena zawiera `access_token`, `token_type` (`Bearer`), `expires_in` (domyślnie 3600 sekund), `refresh_token`, `scope`, `organization_id` oraz `organization_name`. Tokeny dostępu wysyłaj wyłącznie przez nagłówek `Authorization: Bearer`. Nigdy nie umieszczaj tokenów w adresach URL, dziennikach, kontroli wersji ani czacie. ### Odświeżanie i unieważnianie Odśwież token za pomocą `grant_type=refresh_token`, `client_id`, `refresh_token` i `resource` w punkcie końcowym tokenów. Zapisz nowy token odświeżania atomowo i przestań używać starego. Tokeny odświeżania wygasają po 30 dniach bez pomyślnego odświeżenia. Opcjonalny `scope` może zawęzić przyznane uprawnienia. `offline_access` jest zawsze uwzględniany, a tokeny odświeżania są zawsze wydawane. Początkowe żądanie bez `scope` przyznaje jedynie `offline_access`, dlatego klienci powinni żądać potrzebnych im uprawnień. Ponowne użycie kodu i ponowne użycie zrotowanego tokena odświeżania unieważniają całą autoryzację. Serializuj odświeżenia w obrębie klienta; ponowne odtworzenie pomyślnie wymienionego poświadczenia nie jest bezpieczną strategią ponawiania. Aby rozłączyć, wyślij `token` i `client_id` do `POST /v1/oauth/revoke`. Unieważnienie dowolnego tokena unieważnia jego autoryzację, w tym wszystkie tokeny z niego wydane. Nieznany token zwraca powodzenie bez ujawniania, czy istnieje. Sesje panelu mogą wyświetlać własne autoryzacje pod adresem `GET /v1/oauth/grants` i unieważniać je pojedynczo pod adresem `DELETE /v1/oauth/grants/`, przy czym `X-ThunderPhone-Org` wybiera organizację. ### Autoryzacja urządzeń Autoryzacja urządzeń jest ograniczona do wcześniej zarejestrowanych klientów; klienci zarejestrowani dynamicznie otrzymują `unauthorized_client`. Wcześniej zarejestrowany publiczny klient `thunderphone-cli` obsługuje autoryzację urządzeń i odświeżanie. Wyślij `client_id=thunderphone-cli` oraz `scope` do `POST /v1/oauth/device/code`. Wyświetl użytkownikowi `user_code` i `verification_uri` albo otwórz `verification_uri_complete`. Odpytywanie punktu końcowego tokenów wykonuj za pomocą `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` i `device_code`, czekając co najmniej przez zwrócony `interval` (5 sekund). Kontynuuj po `authorization_pending`. Po `slow_down` używaj nowego `interval` zwróconego w odpowiedzi, zwiększonego o 5 sekund, dla każdego kolejnego żądania. Zatrzymaj się po `access_denied`, `expired_token` lub dowolnym innym błędzie. Nigdy nie zatwierdzaj kodu urządzenia automatycznie. Wcześniej zarejestrowany klient `thunderphone-mcp` akceptuje `http://127.0.0.1/callback` i `http://localhost/callback` na dowolnym porcie. Schemat, host, ścieżka i zapytanie muszą być zgodne; wymiana tokena musi używać dokładnego identyfikatora URI przekierowania, łącznie z portem, z autoryzacji. Klienci zarejestrowani dynamicznie wymagają dokładnego dopasowania identyfikatora URI przekierowania, w tym portu. Jeśli potrzebujesz innej ścieżki, zarejestruj dynamicznie inne wywołanie zwrotne. ### Tożsamość konta i kontrole domeny obszaru roboczego Zażądaj zarówno `openid email`, jak i zakresów operacji wymaganych przez klienta. Wywołaj wykryty `userinfo_endpoint` (`GET /v1/oauth/userinfo`) z tokenem dostępu w nagłówku Bearer. Pomyślna odpowiedź zawiera: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` `sub` jest stabilnym identyfikatorem użytkownika; `org_id` to organizacja wybrana podczas wyrażania zgody. Punkt końcowy wymaga obu zakresów tożsamości i zwraca `403`, jeśli któregoś brakuje. Zwraca `403` z `error=access_denied`, jeśli konto nie ma profilu ze zweryfikowanym adresem e-mail, zamiast twierdzić, że niezweryfikowany adres e-mail jest zaufany. Nieprawidłowe, wygasłe, unieważnione lub przeznaczone dla niewłaściwej grupy odbiorców tokeny zwracają `401`. Tokeny sesji użytkownika i klucze API organizacji nie mogą wywoływać userinfo. Token ID nie jest wydawany. ## Dostępne uprawnienia | Rodzina | Zakresy | | --- | --- | | Agenci i importy agentów | `agents:read`, `agents:write` | | Połączenia | `calls:read`, `calls:write` | | Numery telefonów, zablokowani rozmówcy i VoIP | `numbers:read`, `numbers:write` | | Wiedza | `knowledge:read`, `knowledge:write` | | Kampanie | `campaigns:read`, `campaigns:write` | | Integracje, endpointy webhooków, serwery MCP | `integrations:read`, `integrations:write` | | Głosy | `voices:read` | | Scenariusze testowe, uruchomienia testów, walidacja | `testing:read`, `testing:write` | | Rozliczenia | `billing:read` | | Tożsamość konta i zweryfikowany adres e-mail | `openid`, `email` (oba wymagane dla userinfo) | | Trwałe połączenie | `offline_access` (zawsze uwzględniane) | GET, HEAD i OPTIONS używają zakresów odczytu; pozostałe metody używają zakresów zapisu. Modyfikacje głosów i rozliczeń nie są dostępne przez OAuth; `POST /v1/voices/preview` używa `voices:read`, ponieważ umożliwia podgląd głosu bez zmiany jego konfiguracji. Narzędzia MCP egzekwują zakres operacji REST, na której się opierają. Transfery między organizacjami są odrzucane, nawet gdy użytkownik udzielający autoryzacji należy do obu organizacji. Inne rodziny API, w tym zarządzanie kluczami API i ustawienia konta użytkownika, nie są dostępne przez OAuth. Brak wymaganego uprawnienia dla operacji REST zwraca `403` z `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Nieprawidłowe lub wygasłe tokeny dostępu zwracają `401`. ### Sygnały uwierzytelniania narzędzi MCP Każde narzędzie w `tools/list` zawiera `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]`, z zakresem operacji REST danego narzędzia. Publiczne narzędzia dokumentacji używają pustej listy zakresów i nadal wymagają uwierzytelnionego połączenia. Prawidłowy token bez zakresu wymaganego przez narzędzie otrzymuje HTTP `200` z JSON-RPC `result` zawierającym `isError: true`, tekst wyjaśniający w `content` oraz `_meta["mcp/www_authenticate"]`. Ten ostatni element jest tablicą zawierającą wyzwanie Bearer z `resource_metadata`, `error="insufficient_scope"`, `error_description` oraz wymaganym `scope`. Narzędzie nie jest wykonywane. Użyj tego wyzwania, aby zażądać rozszerzonej zgody. Brakujące lub nieprawidłowe uwierzytelnienie nadal zwraca HTTP `401` z `WWW-Authenticate`; błędy zakresu REST nadal zwracają HTTP `403`. ## Przechowywanie poświadczeń API uruchamia `python manage.py oauth_cleanup` co godzinę w środowiskach testowym i produkcyjnym. Usuwa wygasłe żądania autoryzacji i kody urządzeń. Wygasłe tokeny dostępu, kody autoryzacyjne i hasze tokenów odświeżania są usuwane dopiero po cofnięciu ich autoryzacji lub gdy cała rodzina jest nieaktywna. Zużyte hasze są przechowywane, dopóki rodzina ma użyteczny token odświeżania, kod autoryzacyjny, zatwierdzony kod urządzenia lub token dostępu, dzięki czemu czyszczenie nie może wyłączyć wykrywania ponownego użycia.