Open in

Pripojenie pomocou OAuth

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:

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:

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

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

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/<id>, 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:

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