--- title: "Připojení pomocí OAuth" description: "Autorizujte klienty MCP a rozhraní ThunderPhone CLI bez sdílení klíče API." --- OAuth umožňuje aplikaci připojit se k jedné organizaci ThunderPhone s oprávněními, která schválíte. Klienti adresáře by měli OAuth používat ve výchozím nastavení. Klíče API organizace zůstávají dostupné pro klienty, kteří vyžadují ručně nakonfigurovaný token Bearer. ## Schválení připojení Připojení spusťte ve svém klientovi MCP. Přihlaste se do ThunderPhone, zkontrolujte název aplikace a požadovaná oprávnění, vyberte organizaci a zvolte **Schválit**. Pokud jste připojení nespustili nebo aplikaci nedůvěřujete, zvolte **Zamítnout**. Názvy aplikací poskytují jejich vývojáři a nepředstavují ověřovací odznak. Oprávnění ke čtení zpřístupňují uvedená data, včetně nahrávek a přepisů, když je požadováno `calls:read`. Oprávnění k zápisu mohou měnit nebo mazat zdroje; hovory, kampaně, nákupy telefonních čísel a nasazení mohou způsobit náklady nebo ovlivnit produkční prostředí. Vaše role v organizaci nadále platí. Pro připojení přes CLI otevřete ověřovací odkaz zobrazený v terminálu, porovnejte osmimístný kód, vyberte organizaci a připojení schvalte. Pouhé otevření odkazu přístup neuděluje. Kódy vyprší po 15 minutách. ## Odpojení aplikace V dashboardu otevřete **Organizace → Klíče API → Autorizované aplikace** a zvolte **Odvolat**. Tím odvoláte vybrané oprávnění pro aktuální organizaci včetně jejích přístupových a obnovovacích tokenů. Pokud ji chcete znovu autorizovat, znovu se připojte z aplikace. ## Zjišťování pro klienty MCP Použijte adresu URL serveru `https://api.thunderphone.com/v1/mcp`. Požadavek bez platného ověření obdrží `401` s: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Načtěte tento dokument a poté načtěte metadata autorizačního serveru na adrese `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Metadata zdroje jsou dostupná také na `/.well-known/oauth-protected-resource/v1/mcp`. Použijte vrácené koncové body namísto jejich sestavování. Identifikátor zdroje je `https://api.thunderphone.com/v1/mcp`. Server podporuje autorizační kód s **S256 PKCE**, rotující obnovovací tokeny, veřejnou dynamickou registraci klientů, odvolání a tok autorizace zařízení. Neexistují žádná tajemství klientů ani implicitní toky. Zjišťování OpenID je rovněž dostupné na `/.well-known/openid-configuration`; obsahuje stejná pole autorizačního serveru a navíc `subject_types_supported: ["public"]` a koncový bod userinfo. Tokeny ID a dokumenty metadat ID klienta (CIMD) nejsou podporovány. ### Registrace veřejného klienta Odešlete JSON na `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"] } ``` Uložte vrácené `client_id`. Přesměrování musí používat HTTPS nebo HTTP na `127.0.0.1` či `localhost`. Zaregistrujte přesnou adresu URI zpětného volání včetně portu a cesty. Fragmenty a vložené přihlašovací údaje jsou odmítnuty. Volitelné `client_uri` a `logo_uri` musí používat HTTPS; ThunderPhone je během registrace nenačítá. Registrace podléhá omezení rychlosti. Zaregistrovaným klientům nevyprší platnost a po odvolání připojení zůstávají zaregistrováni. Mezi zpětná volání HTTPS patří `https://chatgpt.com/connector/oauth/` a `https://chatgpt.com/connector_platform_oauth_redirect`. Každé připojení může zaregistrovat vlastního klienta. ### Autorizační kód Otevřete zjištěný autorizační koncový bod s `client_id`, přesným zaregistrovaným `redirect_uri`, `response_type=code`, náhodným `state`, `scope`, `code_challenge`, `code_challenge_method=S256` a `resource=https://api.thunderphone.com/v1/mcp`. Výzvu vypočítejte jako neodsazený digest SHA-256 ve formátu base64url z nového ověřovatele PKCE s vysokou entropií. Před výměnou kódu zkontrolujte vrácené hodnoty `state` a `iss`. Každá autorizační odpověď, včetně zamítnutí a chyb protokolu, identifikuje vydavatele pomocí `iss`, které musí přesně odpovídat zjištěnému `issuer`. Chyby neplatného klienta nebo zpětného volání jsou vráceny lokálně bez přesměrování na dané zpětné volání. Proveďte výměnu na `POST /v1/oauth/token` s kódováním formuláře (přijímán je také JSON): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` Volitelný parametr `resource` je přijímán v autorizačních i tokenových požadavcích (včetně výměn obnovovacích tokenů a zařízení). Pokud jej vynecháte, použije se jako výchozí zjištěný zdroj MCP. Je-li uveden, musí přesně odpovídat tomuto zdroji; jiné hodnoty vrátí `invalid_target`. Přístupové tokeny nesou toto publikum a MCP odmítne tokeny s chybějícím nebo odlišným publikem pomocí `401` a výzvy ke zjištění. Platnost autorizačních požadavků a kódů vyprší po 10 minutách. Každá odpověď s tokenem obsahuje `access_token`, `token_type` (`Bearer`), `expires_in` (ve výchozím nastavení 3600 sekund), `refresh_token`, `scope`, `organization_id` a `organization_name`. Přístupové tokeny odesílejte pouze prostřednictvím hlavičky `Authorization: Bearer`. Tokeny nikdy nevkládejte do adres URL, protokolů, správy zdrojového kódu ani chatu. ### Obnovení a odvolání Obnovujte pomocí `grant_type=refresh_token`, `client_id`, `refresh_token` a `resource` na tokenovém koncovém bodě. Nový obnovovací token uložte atomicky a starý přestaňte používat. Platnost obnovovacích tokenů vyprší po 30 dnech bez úspěšného obnovení. Volitelný parametr `scope` může omezit udělená oprávnění. `offline_access` je vždy zahrnut a obnovovací tokeny jsou vždy vydány. Počáteční požadavek bez `scope` udělí pouze `offline_access`, proto by klienti měli požadovat potřebná oprávnění. Opětovné použití kódu a opětovné použití rotovaného obnovovacího tokenu odvolá celou autorizaci. Obnovení v rámci jednoho klienta serializujte; opakované použití úspěšně vyměněného přihlašovacího údaje není bezpečná strategie opakování. Chcete-li odpojit, odešlete `token` a `client_id` na `POST /v1/oauth/revoke`. Odvoláním kteréhokoli tokenu odvoláte jeho autorizaci včetně všech tokenů z něj vydaných. Neznámý token vrátí úspěch, aniž by prozradil, zda existuje. Relace v dashboardu mohou zobrazit vlastní autorizace na `GET /v1/oauth/grants` a jednu odvolat na `DELETE /v1/oauth/grants/`, přičemž `X-ThunderPhone-Org` vybírá organizaci. ### Autorizace zařízení Autorizace zařízení je omezena na předem zaregistrované klienty; dynamicky zaregistrovaní klienti obdrží `unauthorized_client`. Předem zaregistrovaný veřejný klient `thunderphone-cli` podporuje autorizaci zařízení a obnovení. Odešlete `client_id=thunderphone-cli` a `scope` na `POST /v1/oauth/device/code`. Uživateli zobrazte `user_code` a `verification_uri` nebo otevřete `verification_uri_complete`. Dotazujte se tokenového koncového bodu pomocí `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` a `device_code` a čekejte alespoň vrácený `interval` (5 sekund). Pokračujte při `authorization_pending`. Při `slow_down` použijte pro každý následující požadavek nový `interval` vrácený v odpovědi (zvýšený o 5 sekund). Zastavte při `access_denied`, `expired_token` nebo jakékoli jiné chybě. Kód zařízení nikdy neschvalujte automaticky. Předem zaregistrovaný klient `thunderphone-mcp` přijímá `http://127.0.0.1/callback` a `http://localhost/callback` na libovolném portu. Schéma, hostitel, cesta a dotaz musí odpovídat; výměna tokenu musí použít přesnou adresu URI přesměrování (včetně portu) z autorizace. Dynamicky zaregistrovaní klienti vyžadují přesnou shodu adresy URI přesměrování včetně portu. Pokud potřebujete jinou cestu, zaregistrujte dynamicky jiné zpětné volání. ### Kontroly identity účtu a domény pracovního prostoru Požadujte obě oprávnění `openid email` spolu s oprávněními operací, která váš klient potřebuje. Zavolejte zjištěný `userinfo_endpoint` (`GET /v1/oauth/userinfo`) s přístupovým tokenem v hlavičce Bearer. Úspěšná odpověď obsahuje: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` `sub` je stabilní identifikátor uživatele; `org_id` je organizace vybraná během souhlasu. Koncový bod vyžaduje obě oprávnění identity a vrátí `403`, pokud některé chybí. Pokud účet nemá profil s ověřeným e-mailem, vrátí `403` s `error=access_denied`, namísto tvrzení, že neověřený e-mail je důvěryhodný. Neplatné tokeny, tokeny po vypršení platnosti, odvolané tokeny nebo tokeny s nesprávným publikem vrátí `401`. Tokeny relací lidí a klíče API organizace nemohou volat userinfo. Token ID se nevydává. ## Dostupná oprávnění | Oblast | Oprávnění | | --- | --- | | Agenti a importy agentů | `agents:read`, `agents:write` | | Hovory | `calls:read`, `calls:write` | | Telefonní čísla, blokující volající a VoIP | `numbers:read`, `numbers:write` | | Znalosti | `knowledge:read`, `knowledge:write` | | Kampaně | `campaigns:read`, `campaigns:write` | | Integrace, koncové body webhooků, servery MCP | `integrations:read`, `integrations:write` | | Hlasy | `voices:read` | | Testovací scénáře, testovací běhy, validace | `testing:read`, `testing:write` | | Fakturace | `billing:read` | | Identita účtu a ověřený e-mail | `openid`, `email` (obě jsou vyžadovány pro userinfo) | | Trvalé připojení | `offline_access` (vždy zahrnuto) | GET, HEAD a OPTIONS používají rozsahy pro čtení; ostatní metody používají rozsahy pro zápis. Změny hlasů a fakturace nejsou prostřednictvím OAuth dostupné; `POST /v1/voices/preview` používá `voices:read`, protože zobrazuje náhled hlasu bez změny jeho konfigurace. Nástroje MCP vynucují rozsah své podkladové operace REST. Převody mezi organizacemi jsou zamítnuty, i když autorizující uživatel patří do obou organizací. Další oblasti API, včetně správy klíčů API a nastavení uživatelského účtu, nejsou prostřednictvím OAuth dostupné. Chybějící oprávnění pro operaci REST vrátí `403` s `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Neplatné nebo expirované přístupové tokeny vrátí `401`. ### Signály ověřování nástrojů MCP Každý nástroj v `tools/list` obsahuje `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]` s rozsahem operace REST daného nástroje. Veřejné nástroje dokumentace používají prázdný seznam rozsahů a stále vyžadují ověřené připojení. Platný token, kterému chybí rozsah nástroje, obdrží HTTP `200` s JSON-RPC `result` obsahujícím `isError: true`, vysvětlující text v `content` a `_meta["mcp/www_authenticate"]`. Poslední položka je pole obsahující výzvu Bearer s `resource_metadata`, `error="insufficient_scope"`, `error_description` a požadovaným `scope`. Nástroj se nespustí. Pomocí této výzvy požádejte o rozšířený souhlas. Chybějící nebo neplatné ověření nadále vrací HTTP `401` s `WWW-Authenticate`; selhání rozsahu REST nadále vrací HTTP `403`. ## Uchovávání přihlašovacích údajů API spouští `python manage.py oauth_cleanup` každou hodinu ve stagingu i produkci. Odstraňuje expirované požadavky na autorizaci a kódy zařízení. Expirované přístupové tokeny, autorizační kódy a hashe obnovovacích tokenů jsou odstraněny až po odvolání jejich oprávnění nebo po zneplatnění celé rodiny. Použité hashe jsou uchovávány, dokud má rodina použitelný obnovovací token, autorizační kód, schválený kód zařízení nebo přístupový token, takže čištění nemůže deaktivovat detekci opakovaného použití.