--- title: "Pripojenie pomocou OAuth" description: "Autorizujte klientov MCP a rozhranie príkazového riadka ThunderPhone bez zdieľania kľúča API." --- OAuth umožňuje aplikácii pripojiť sa k jednej organizácii ThunderPhone s oprávneniami, ktoré schválite. Klienti adresára by mali predvolene používať OAuth. Kľúče API organizácie zostávajú k dispozícii pre klientov, ktorí vyžadujú manuálne nakonfigurovaný token Bearer. ## Schválenie pripojenia Spustite pripojenie vo svojom klientovi MCP. Prihláste sa do ThunderPhone, skontrolujte názov aplikácie a požadované oprávnenia, vyberte organizáciu a zvoľte **Schváliť**. Ak ste pripojenie nespustili alebo aplikácii nedôverujete, zvoľte **Zamietnuť**. Názvy aplikácií poskytujú ich vývojári a nepredstavujú odznak overenia. Oprávnenia na čítanie sprístupňujú uvedené údaje vrátane nahrávok a prepisov, keď sa požaduje `calls:read`. Oprávnenia na zápis môžu meniť alebo odstraňovať zdroje; hovory, kampane, nákupy telefónnych čísel a nasadenia môžu spôsobovať náklady alebo ovplyvniť produkčné prostredie. Vaša rola v organizácii naďalej platí. Pri pripojení cez CLI otvorte overovací odkaz zobrazený v termináli, porovnajte osemznakový kód, vyberte svoju organizáciu a schváľte pripojenie. Samotné otvorenie odkazu neudeľuje prístup. Kódy vypršia po 15 minútach. ## Odpojenie aplikácie Na paneli otvorte **Organizácia → Kľúče API → Autorizované aplikácie** a zvoľte **Zrušiť oprávnenie**. Tým sa zruší vaše vybrané autorizovanie pre aktuálnu organizáciu vrátane jej prístupových a obnovovacích tokenov. Ak ju chcete autorizovať znova, pripojte sa z aplikácie opätovne. ## Objavovanie pre klientov MCP Použite URL servera `https://api.thunderphone.com/v1/mcp`. Požiadavka bez platného overenia dostane odpoveď `401` s: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Načítajte tento dokument a potom metadáta autorizačného servera na adrese `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Metadáta zdroja sú dostupné aj na adrese `/.well-known/oauth-protected-resource/v1/mcp`. Použite vrátené koncové body namiesto ich vytvárania. Identifikátor zdroja je `https://api.thunderphone.com/v1/mcp`. Server podporuje autorizačný kód s **S256 PKCE**, rotujúce obnovovacie tokeny, verejnú dynamickú registráciu klientov, odvolanie a grant autorizácie zariadenia. Neexistujú žiadne tajné kľúče klienta ani implicitné granty. Objavovanie OpenID je dostupné aj na adrese `/.well-known/openid-configuration`; zahŕňa rovnaké polia autorizačného servera a navyše `subject_types_supported: ["public"]` a koncový bod userinfo. ID tokeny a dokumenty metadát ID klienta (CIMD) nie sú podporované. ### Zaregistrovanie verejného klienta Odošlite 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átený `client_id`. Presmerovania musia používať HTTPS alebo HTTP na `127.0.0.1` či `localhost`. Zaregistrujte presnú URI spätného volania vrátane jej portu a cesty. Fragmenty a vložené prihlasovacie údaje sú odmietnuté. Voliteľné `client_uri` a `logo_uri` musia používať HTTPS; ThunderPhone ich počas registrácie nenačítava. Registrácia je obmedzená počtom požiadaviek. Zaregistrovaní klienti neexpirujú a zostávajú zaregistrovaní aj po odvolaní pripojenia. Spätné volania HTTPS zahŕňajú `https://chatgpt.com/connector/oauth/` a `https://chatgpt.com/connector_platform_oauth_redirect`. Každé pripojenie môže zaregistrovať vlastného klienta. ### Autorizačný kód Otvorte objavený autorizačný koncový bod s parametrami `client_id`, presný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čítajte ako nevyplnený base64url SHA-256 digest nového PKCE overovača s vysokou entropiou. Pred výmenou kódu overte vrátené `state` a `iss`. Každá autorizačná odpoveď vrátane odmietnutia a chýb protokolu identifikuje vydavateľa pomocou `iss`, ktoré sa presne zhoduje s objaveným `issuer`. Chyby neplatného klienta alebo spätného volania sa vracajú lokálne bez presmerovania na dané spätné volanie. Vymeňte na `POST /v1/oauth/token` pomocou kódovania formulára (akceptuje sa aj JSON): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` Voliteľný parameter `resource` sa akceptuje v autorizačných požiadavkách aj požiadavkách na tokeny (vrátane výmeny obnovenia a zariadenia). Ak je vynechaný, predvolene sa použije objavený zdroj MCP. Ak je uvedený, musí sa presne zhodovať s týmto zdrojom; iné hodnoty vrátia `invalid_target`. Prístupové tokeny obsahujú toto publikum a MCP odmieta tokeny s chýbajúcim alebo odlišným publikom odpoveďou `401` a výzvou na objavenie. Autorizačné požiadavky a kódy expirujú po 10 minútach. Každá odpoveď s tokenom obsahuje `access_token`, `token_type` (`Bearer`), `expires_in` (predvolene 3600 sekúnd), `refresh_token`, `scope`, `organization_id` a `organization_name`. Prístupové tokeny odosielajte iba prostredníctvom hlavičky `Authorization: Bearer`. Tokeny nikdy nevkladajte do URL, protokolov, správy zdrojového kódu ani chatu. ### Obnovenie a odvolanie Obnovte pomocou `grant_type=refresh_token`, `client_id`, `refresh_token` a `resource` na koncovom bode tokenov. Nový obnovovací token uložte atómovo a starý prestaňte používať. Obnovovacie tokeny expirujú po 30 dňoch bez úspešného obnovenia. Voliteľný parameter `scope` môže zúžiť udelené oprávnenia. `offline_access` je vždy zahrnutý a obnovovacie tokeny sa vydávajú vždy. Počiatočná požiadavka bez `scope` udeľuje iba `offline_access`, preto by klienti mali požadovať oprávnenia, ktoré potrebujú. Opätovné použitie kódu a opätovné použitie rotovaného obnovovacieho tokenu odvolá celé autorizovanie. Obnovenia v rámci klienta serializujte; opätovné prehratie úspešne vymeneného poverenia nie je bezpečná stratégia opakovania. Ak chcete odpojiť, odošlite `token` a `client_id` na `POST /v1/oauth/revoke`. Odvolanie ktoréhokoľvek tokenu odvolá jeho autorizáciu vrátane všetkých tokenov z neho vydaných. Neznámy token vráti úspech bez prezradenia, či existuje. Relácie ovládacieho panela môžu uviesť vlastné autorizácie na `GET /v1/oauth/grants` a odvolať jednu na `DELETE /v1/oauth/grants/`, pričom organizáciu vyberá `X-ThunderPhone-Org`. ### Autorizácia zariadenia Autorizácia zariadenia je obmedzená na vopred zaregistrovaných klientov; dynamicky zaregistrovaní klienti dostanú `unauthorized_client`. Vopred zaregistrovaný verejný klient `thunderphone-cli` podporuje autorizáciu zariadenia a obnovenie. Odošlite `client_id=thunderphone-cli` a `scope` na `POST /v1/oauth/device/code`. Používateľovi zobrazte `user_code` a `verification_uri` alebo otvorte `verification_uri_complete`. Dotazujte koncový bod tokenov pomocou `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` a `device_code`, pričom počkajte aspoň vrátený `interval` (5 sekúnd). Pri `authorization_pending` pokračujte. Pri `slow_down` použite nový `interval` vrátený v odpovedi (zvýšený o 5 sekúnd) pre každú nasledujúcu požiadavku. Zastavte pri `access_denied`, `expired_token` alebo akejkoľvek inej chybe. Kód zariadenia nikdy neschvaľujte automaticky. Vopred zaregistrovaný klient `thunderphone-mcp` akceptuje `http://127.0.0.1/callback` a `http://localhost/callback` na akomkoľvek porte. Schéma, hostiteľ, cesta a dopyt sa musia zhodovať; výmena tokenu musí použiť presnú URI presmerovania (vrátane portu) z autorizácie. Dynamicky zaregistrovaní klienti vyžadujú presnú zhodu URI presmerovania vrátane portu. Ak potrebujete inú cestu, zaregistrujte dynamicky iné spätné volanie. ### Overovanie identity účtu a domény pracovného priestoru Požadujte `openid email` spolu s rozsahmi operácií, ktoré váš klient potrebuje. Zavolajte objavený `userinfo_endpoint` (`GET /v1/oauth/userinfo`) s prístupovým tokenom v hlavičke Bearer. Úspešná odpoveď obsahuje: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` `sub` je stabilný identifikátor používateľa; `org_id` je organizácia vybraná počas súhlasu. Koncový bod vyžaduje oba rozsahy identity a vráti `403`, ak niektorý chýba. Vráti `403` s `error=access_denied`, ak účet nemá profil s overeným e-mailom, namiesto tvrdenia, že neoverenému e-mailu možno dôverovať. Neplatné, expirované, odvolané tokeny alebo tokeny s nesprávnym publikom vrátia `401`. Tokeny relácií ľudí a kľúče API organizácie nemôžu volať userinfo. Nevydáva sa žiadny ID token. ## Dostupné oprávnenia | Oblasť | Rozsahy | | --- | --- | | Agenti a importy agentov | `agents:read`, `agents:write` | | Hovory | `calls:read`, `calls:write` | | Telefónne čísla a VoIP | `numbers:read`, `numbers:write` | | Znalosti | `knowledge:read`, `knowledge:write` | | Kampane | `campaigns:read`, `campaigns:write` | | Integrácie, koncové body webhookov, servery MCP | `integrations:read`, `integrations:write` | | Hlasy | `voices:read` | | Testovacie scenáre, testovacie spustenia, overovanie | `testing:read`, `testing:write` | | Fakturácia | `billing:read` | | Identita účtu a overený e-mail | `openid`, `email` (obe sú povinné pre userinfo) | | Trvalé pripojenie | `offline_access` (vždy zahrnuté) | GET, HEAD a OPTIONS používajú rozsahy čítania; ostatné metódy používajú rozsahy zápisu. Zmeny hlasov a fakturácie nie sú prostredníctvom OAuth dostupné; `POST /v1/voices/preview` používa `voices:read`, pretože vytvára náhľad hlasu bez zmeny jeho konfigurácie. Nástroje MCP vynucujú rozsah svojej základnej operácie REST. Prenosy medzi organizáciami sú zamietnuté aj vtedy, keď používateľ udeľujúci autorizáciu patrí do oboch organizácií. Ostatné oblasti API vrátane správy kľúčov API a nastavení používateľských účtov nie sú prostredníctvom OAuth dostupné. Chýbajúce oprávnenie pre operáciu REST vráti `403` s `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Neplatné alebo expirované prístupové tokeny vrátia `401`. ### Signály autentifikácie nástrojov MCP Každý nástroj v `tools/list` obsahuje `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]` s rozsahom operácie REST daného nástroja. Verejné nástroje dokumentácie používajú prázdny zoznam rozsahov a naďalej vyžadujú autentifikované pripojenie. Platný token, ktorému chýba rozsah nástroja, dostane HTTP `200` s JSON-RPC `result` obsahujúcim `isError: true`, vysvetľujúci text v `content` a `_meta["mcp/www_authenticate"]`. Posledný uvedený prvok je pole obsahujúce výzvu Bearer s `resource_metadata`, `error="insufficient_scope"`, `error_description` a požadovaným `scope`. Nástroj sa nevykoná. Túto výzvu použite na vyžiadanie rozšíreného súhlasu. Chýbajúca alebo neplatná autentifikácia naďalej vracia HTTP `401` s `WWW-Authenticate`; zlyhania rozsahu REST naďalej vracajú HTTP `403`. ## Uchovávanie poverení API spúšťa `python manage.py oauth_cleanup` každú hodinu v prostrediach staging a production. Odstraňuje expirované žiadosti o autorizáciu a kódy zariadení. Expirované prístupové tokeny, autorizačné kódy a haše obnovovacích tokenov sa odstránia až po odvolaní ich grantu alebo po zneplatnení celej rodiny tokenov. Použité haše sa uchovávajú, kým má rodina použiteľný obnovovací token, autorizačný kód, schválený kód zariadenia alebo prístupový token, takže čistenie nemôže zakázať detekciu opakovaného použitia.