Připojení pomocí OAuth

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:

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:

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

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

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

{
  "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í#

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í.