Open in

Połącz za pomocą OAuth

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:

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:

{
  "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/<id> 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):

grant_type=authorization_code
client_id=<your client id>
code=<single-use authorization code>
redirect_uri=<exact registered redirect URI>
code_verifier=<original PKCE 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/<id>, 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:

{
  "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.