--- title: "Povežite se s OAuthom" description: "Autorizirajte MCP klijente i ThunderPhone CLI bez dijeljenja API ključa." --- OAuth omogućuje aplikaciji povezivanje s jednom organizacijom ThunderPhone s dozvolama koje odobrite. Klijenti direktorija trebali bi prema zadanim postavkama koristiti OAuth. Organizacijski API ključevi i dalje su dostupni za klijente kojima je potreban ručno konfiguriran Bearer token. ## Odobrite povezivanje Pokrenite povezivanje u svom MCP klijentu. Prijavite se u ThunderPhone, provjerite naziv aplikacije i zatražene dozvole, odaberite organizaciju i odaberite **Odobri**. Odaberite **Odbij** ako niste pokrenuli povezivanje ili ne vjerujete aplikaciji. Nazive aplikacija navode njihovi razvojni programeri i oni nisu oznaka provjere. Dozvole za čitanje otkrivaju navedene podatke, uključujući snimke i prijepise kada se zatraži `calls:read`. Dozvole za pisanje mogu promijeniti ili izbrisati resurse; pozivi, kampanje, kupnje telefonskih brojeva i implementacije mogu uzrokovati troškove ili utjecati na produkciju. Vaša uloga u organizaciji i dalje vrijedi. Za CLI povezivanje otvorite vezu za provjeru prikazanu u terminalu, usporedite osmeroznamenkasti kôd, odaberite organizaciju i odobrite povezivanje. Samo otvaranje veze ne odobrava pristup. Kôdovi istječu nakon 15 minuta. ## Prekinite povezivanje aplikacije Na nadzornoj ploči otvorite **Organizacija → API ključevi → Ovlaštene aplikacije** i odaberite **Opozovi**. Time se opoziva vaše odabrano ovlaštenje za trenutačnu organizaciju, uključujući njezine pristupne tokene i tokene za osvježavanje. Ponovno se povežite iz aplikacije ako je želite ponovno ovlastiti. ## Otkrivanje za MCP klijente Upotrijebite URL poslužitelja `https://api.thunderphone.com/v1/mcp`. Zahtjev bez valjane autentifikacije prima `401` uz: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Dohvatite taj dokument, a zatim dohvatite metapodatke autorizacijskog poslužitelja na `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Metapodaci resursa dostupni su i na `/.well-known/oauth-protected-resource/v1/mcp`. Upotrijebite vraćene krajnje točke umjesto da ih sastavljate. Identifikator resursa jest `https://api.thunderphone.com/v1/mcp`. Poslužitelj podržava autorizacijski kôd sa **S256 PKCE**, rotirajuće tokene za osvježavanje, javnu dinamičku registraciju klijenta, opoziv i dodjelu autorizacije uređaja. Ne postoje tajne klijenta ni implicitne dodjele. OpenID otkrivanje također je dostupno na `/.well-known/openid-configuration`; uključuje ista polja autorizacijskog poslužitelja te `subject_types_supported: ["public"]` i krajnju točku userinfo. ID tokeni i dokumenti metapodataka ID-a klijenta (CIMD) nisu podržani. ### Registrirajte javnog klijenta Pošaljite 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"] } ``` Spremite vraćeni `client_id`. Preusmjeravanja moraju upotrebljavati HTTPS ili HTTP na `127.0.0.1` ili `localhost`. Registrirajte točan URI povratnog poziva, uključujući njegov priključak i putanju. Fragmenti i ugrađene vjerodajnice odbijaju se. Neobavezni `client_uri` i `logo_uri` moraju upotrebljavati HTTPS; ThunderPhone ih ne dohvaća tijekom registracije. Registracija je ograničena stopom zahtjeva. Registrirani klijenti ne istječu i ostaju registrirani kada se veza opozove. HTTPS povratni pozivi uključuju `https://chatgpt.com/connector/oauth/` i `https://chatgpt.com/connector_platform_oauth_redirect`. Svaka veza može registrirati vlastitog klijenta. ### Autorizacijski kôd Otvorite otkrivenu krajnju točku za autorizaciju s parametrima `client_id`, točnim registriranim `redirect_uri`, `response_type=code`, nasumičnim `state`, `scope`, `code_challenge`, `code_challenge_method=S256` i `resource=https://api.thunderphone.com/v1/mcp`. Izračunajte izazov kao base64url SHA-256 sažetak bez dopune svježeg PKCE provjeravatelja visoke entropije. Provjerite vraćene `state` i `iss` prije razmjene koda. Svaki odgovor na autorizaciju, uključujući odbijanje i pogreške protokola, identificira izdavatelja pomoću `iss`, koji točno odgovara otkrivenom `issuer`. Pogreške za nevaljanog klijenta ili povratni poziv vraćaju se lokalno bez preusmjeravanja na taj povratni poziv. Izmijenite na `POST /v1/oauth/token` upotrebom kodiranja obrasca (prihvaća se i JSON): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` Neobavezni parametar `resource` prihvaća se u zahtjevima za autorizaciju i token (uključujući razmjene za osvježavanje i uređaj). Kada je izostavljen, zadano je otkriveni MCP resurs. Kada je prisutan, mora točno odgovarati tom resursu; druge vrijednosti vraćaju `invalid_target`. Pristupni tokeni sadrže tu publiku, a MCP odbija tokene s nedostajućom ili drukčijom publikom s `401` i izazovom za otkrivanje. Zahtjevi za autorizaciju i kodovi istječu nakon 10 minuta. Svaki odgovor s tokenom sadržava `access_token`, `token_type` (`Bearer`), `expires_in` (zadano 3600 sekundi), `refresh_token`, `scope`, `organization_id` i `organization_name`. Pristupne tokene šaljite samo putem zaglavlja `Authorization: Bearer`. Nikada ne stavljajte tokene u URL-ove, zapisnike, kontrolu izvornog koda ni chat. ### Osvježite i opozovite Osvježite s parametrima `grant_type=refresh_token`, `client_id`, `refresh_token` i `resource` na krajnjoj točki za token. Novi token za osvježavanje spremite atomski i prestanite upotrebljavati stari. Tokeni za osvježavanje istječu nakon 30 dana bez uspješnog osvježavanja. Neobavezni `scope` može suziti dodijeljena dopuštenja. `offline_access` uvijek je uključen i tokeni za osvježavanje uvijek se izdaju. Početni zahtjev bez `scope` dodjeljuje samo `offline_access`, stoga klijenti trebaju zatražiti dopuštenja koja trebaju. Ponovna upotreba koda i ponovna upotreba rotiranog tokena za osvježavanje opozivaju cijelu autorizaciju. Serijalizirajte osvježavanja unutar klijenta; ponavljanje uspješno razmijenjene vjerodajnice nije sigurna strategija ponovnog pokušaja. Za prekid veze pošaljite `token` i `client_id` na `POST /v1/oauth/revoke`. Opozivanje bilo kojeg tokena opoziva njegovu autorizaciju, uključujući sve tokene izdane iz njega. Nepoznati token vraća uspjeh bez otkrivanja postoji li. Sesije nadzorne ploče mogu navesti vlastite autorizacije na `GET /v1/oauth/grants` i opozvati jednu na `DELETE /v1/oauth/grants/`, pri čemu `X-ThunderPhone-Org` odabire organizaciju. ### Autorizacija uređaja Autorizacija uređaja ograničena je na unaprijed registrirane klijente; dinamički registrirani klijenti primaju `unauthorized_client`. Unaprijed registrirani javni klijent `thunderphone-cli` podržava autorizaciju uređaja i osvježavanje. Pošaljite `client_id=thunderphone-cli` i `scope` na `POST /v1/oauth/device/code`. Korisniku prikažite `user_code` i `verification_uri` ili otvorite `verification_uri_complete`. Ispitujte krajnju točku za token s parametrima `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` i `device_code`, čekajući najmanje vraćeni `interval` (5 sekundi). Nastavite pri `authorization_pending`. Pri `slow_down` za svaki sljedeći zahtjev upotrijebite novi `interval` vraćen u odgovoru (povećan za 5 sekundi). Zaustavite se pri `access_denied`, `expired_token` ili bilo kojoj drugoj pogrešci. Nikada automatski ne odobravajte kôd uređaja. Unaprijed registrirani klijent `thunderphone-mcp` prihvaća `http://127.0.0.1/callback` i `http://localhost/callback` na bilo kojem priključku. Shema, host, putanja i upit moraju odgovarati; razmjena tokena mora upotrebljavati točan URI preusmjeravanja (uključujući priključak) iz autorizacije. Dinamički registrirani klijenti zahtijevaju točno podudaranje URI-ja preusmjeravanja, uključujući priključak. Dinamički registrirajte drukčiji povratni poziv ako vam je potrebna druga putanja. ### Provjere identiteta računa i domene radnog prostora Zatražite oba opsega `openid email` uz opsege operacija koje vaš klijent treba. Pozovite otkrivenu `userinfo_endpoint` (`GET /v1/oauth/userinfo`) s pristupnim tokenom u zaglavlju Bearer. Uspješan odgovor sadržava: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` `sub` je stabilni identifikator korisnika; `org_id` je organizacija odabrana tijekom pristanka. Krajnja točka zahtijeva oba opsega identiteta i vraća `403` ako bilo koji nedostaje. Vraća `403` s `error=access_denied` ako račun nema profil s potvrđenom e-poštom, umjesto da tvrdi da je nepotvrđena e-pošta pouzdana. Nevaljani, istekli, opozvani tokeni ili tokeni s pogrešnom publikom vraćaju `401`. Tokeni sesije korisnika i API ključevi organizacije ne mogu pozvati userinfo. ID token se ne izdaje. ## Dostupne dozvole | Obitelj | Opsezi | | --- | --- | | Agenti i uvoz agenata | `agents:read`, `agents:write` | | Pozivi | `calls:read`, `calls:write` | | Telefonski brojevi i VoIP | `numbers:read`, `numbers:write` | | Znanje | `knowledge:read`, `knowledge:write` | | Kampanje | `campaigns:read`, `campaigns:write` | | Integracije, krajnje točke webhooka, MCP poslužitelji | `integrations:read`, `integrations:write` | | Glasovi | `voices:read` | | Testni scenariji, pokretanja testova, provjera valjanosti | `testing:read`, `testing:write` | | Naplata | `billing:read` | | Identitet računa i potvrđena e-pošta | `openid`, `email` (oba su potrebna za userinfo) | | Trajna veza | `offline_access` (uvijek uključen) | GET, HEAD i OPTIONS koriste opsege za čitanje; druge metode koriste opsege za pisanje. Izmjene glasova i naplate nisu dostupne putem OAutha; `POST /v1/voices/preview` koristi `voices:read` jer pregledava glas bez promjene njegove konfiguracije. MCP alati primjenjuju opseg svoje temeljne REST operacije. Prijenosi između organizacija odbijaju se čak i kada korisnik koji autorizira pripada objema organizacijama. Ostale API obitelji, uključujući upravljanje API ključevima i postavke korisničkih računa, nisu dostupne putem OAutha. Nedostajuća dozvola za REST operaciju vraća `403` s `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Nevažeći ili istekli pristupni tokeni vraćaju `401`. ### Signali autentikacije MCP alata Svaki alat u `tools/list` uključuje `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]`, s opsegom REST operacije tog alata. Alati za javnu dokumentaciju koriste prazan popis opsega i i dalje zahtijevaju autentificiranu vezu. Valjani token kojem nedostaje opseg alata prima HTTP `200` s JSON-RPC `result` koji sadrži `isError: true`, objašnjavajući tekst u `content` i `_meta["mcp/www_authenticate"]`. Potonji je polje koje sadrži Bearer izazov s `resource_metadata`, `error="insufficient_scope"`, `error_description` i potrebnim `scope`. Alat se ne izvršava. Upotrijebite ovaj izazov za zahtjev proširene privole. Nedostajuća ili nevažeća autentikacija i dalje vraća HTTP `401` s `WWW-Authenticate`; pogreške REST opsega i dalje vraćaju HTTP `403`. ## Zadržavanje vjerodajnica API pokreće `python manage.py oauth_cleanup` svakog sata u staging i produkcijskom okruženju. Uklanja istekle zahtjeve za autorizaciju i kodove uređaja. Istekli pristupni tokeni, autorizacijski kodovi i sažeci refresh tokena uklanjaju se tek nakon što se njihovo odobrenje opozove ili cijela obitelj više nije aktivna. Iskorišteni sažeci zadržavaju se dok obitelj ima upotrebljiv refresh token, autorizacijski kod, odobreni kod uređaja ili pristupni token, kako čišćenje ne bi moglo onemogućiti otkrivanje ponovne upotrebe.