--- title: "Ühenda OAuthiga" description: "Volita MCP-kliente ja ThunderPhone'i CLI-d ilma API-võtit jagamata." --- OAuth võimaldab rakendusel luua ühenduse ühe ThunderPhone’i organisatsiooniga sinu heakskiidetud õigustega. Kataloogikliendid peaksid vaikimisi kasutama OAuthi. Organisatsiooni API võtmed on endiselt saadaval klientidele, mis vajavad käsitsi seadistatud Bearer-tokenit. ## Kinnita ühendus Alusta ühendust oma MCP-kliendis. Logi ThunderPhone’i sisse, kontrolli rakenduse nime ja taotletud õigusi, vali organisatsioon ning vali **Kinnita**. Vali **Keela**, kui sa ei algatanud ühendust või ei usalda rakendust. Rakenduste nimed määravad nende arendajad ning need ei ole kinnitusmärgis. Lugemisõigused võimaldavad juurdepääsu nimetatud andmetele, sealhulgas salvestistele ja transkriptsioonidele, kui taotletakse õigust `calls:read`. Kirjutamisõigused võivad ressursse muuta või kustutada; kõned, kampaaniad, telefoninumbrite ostud ja juurutused võivad tekitada kulusid või mõjutada tootmiskeskkonda. Sinu organisatsiooni roll kehtib endiselt. CLI-ühenduse jaoks ava terminalis kuvatav kinnitamislink, võrdle kaheksakohalist koodi, vali oma organisatsioon ja kinnita. Ainult lingi avamine ei anna juurdepääsu. Koodid aeguvad 15 minuti pärast. ## Katkesta rakenduse ühendus Ava juhtpaneelil **Organisatsioon → API võtmed → Volitatud rakendused** ja vali **Tühista**. See tühistab sinu valitud volituse praeguse organisatsiooni jaoks, sealhulgas selle juurdepääsu- ja värskendustokenid. Kui soovid rakendust uuesti volitada, loo ühendus rakendusest uuesti. ## MCP-klientide tuvastamine Kasuta serveri URL-i `https://api.thunderphone.com/v1/mcp`. Kehtiva autentimiseta päring saab vastuseks `401` koos: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Hangi see dokument ja seejärel autoriseerimisserveri metaandmed aadressilt `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Ressursi metaandmed on saadaval ka aadressil `/.well-known/oauth-protected-resource/v1/mcp`. Kasuta tagastatud lõpp-punkte nende käsitsi koostamise asemel. Ressursi identifikaator on `https://api.thunderphone.com/v1/mcp`. Server toetab autoriseerimiskoodi voogu koos **S256 PKCE-ga**, roteeruvaid värskendustokeneid, avalikku dünaamilist kliendi registreerimist, tühistamist ja seadme autoriseerimise voogu. Kliendisaladusi ega kaudseid vooge ei ole. OpenID tuvastamine on samuti saadaval aadressil `/.well-known/openid-configuration`; see sisaldab samu autoriseerimisserveri välju ning `subject_types_supported: ["public"]` ja userinfo lõpp-punkti. ID-tokenid ja kliendi ID metaandmedokumendid (CIMD) ei ole toetatud. ### Registreeri avalik klient Saada JSON päringule `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"] } ``` Salvesta tagastatud `client_id`. Ümbersuunamised peavad kasutama HTTPS-i või HTTP-d aadressil `127.0.0.1` või `localhost`. Registreeri täpne tagasihelistamise URI koos pordi ja teega. Fragmente ja manustatud mandaate ei aktsepteerita. Valikulised `client_uri` ja `logo_uri` peavad kasutama HTTPS-i; ThunderPhone ei hangi neid registreerimise ajal. Registreerimisel on kiirusepiirang. Registreeritud kliendid ei aegu ning jäävad registreerituks ka ühenduse tühistamisel. HTTPS-i tagasihelistamiste hulka kuuluvad `https://chatgpt.com/connector/oauth/` ja `https://chatgpt.com/connector_platform_oauth_redirect`. Iga ühendus võib registreerida oma kliendi. ### Autoriseerimiskood Ava tuvastatud autoriseerimise lõpp-punkt parameetritega `client_id`, täpselt registreeritud `redirect_uri`, `response_type=code`, juhuslik `state`, `scope`, `code_challenge`, `code_challenge_method=S256` ja `resource=https://api.thunderphone.com/v1/mcp`. Arvuta prooviväärtus värske suure entroopiaga PKCE kontrollväärtuse polsterdamata base64url-vormingus SHA-256 räsi põhjal. Kontrolli tagastatud `state` ja `iss` enne koodi vahetamist. Iga autoriseerimisvastus, sealhulgas keeldumine ja protokollivead, tuvastab väljaandja väljal `iss`, mis vastab täpselt tuvastatud `issuer` väärtusele. Kehtetu kliendi või tagasihelistamise vead tagastatakse kohalikult, ilma sellele tagasihelistamise aadressile ümber suunamata. Vaheta kood päringuga `POST /v1/oauth/token`, kasutades vormingut form encoding (aktsepteeritakse ka JSON-i): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` Valikuline parameeter `resource` on aktsepteeritud nii autoriseerimis- kui ka tokenipäringutes, sealhulgas värskendamise ja seadmevahetuse korral. Kui see on välja jäetud, kasutatakse vaikimisi tuvastatud MCP ressurssi. Kui see on olemas, peab see vastama sellele ressursile täpselt; muud väärtused tagastavad `invalid_target`. Juurdepääsutokenid sisaldavad seda sihtrühma ning MCP lükkab puuduva või erineva sihtrühmaga tokenid tagasi vastusega `401` ja tuvastamiskutsega. Autoriseerimispäringud ja koodid aeguvad 10 minuti pärast. Iga tokenivastus sisaldab `access_token`, `token_type` (`Bearer`), `expires_in` (vaikimisi 3600 sekundit), `refresh_token`, `scope`, `organization_id` ja `organization_name`. Saada juurdepääsutokenid ainult päise `Authorization: Bearer` kaudu. Ära kunagi lisa tokeneid URL-idesse, logidesse, lähtekoodi versioonihaldusse ega vestlustesse. ### Värskenda ja tühista Värskenda tokeni lõpp-punktis parameetritega `grant_type=refresh_token`, `client_id`, `refresh_token` ja `resource`. Salvesta uus värskendustoken atomaarse toiminguna ning lõpeta vana kasutamine. Värskendustokenid aeguvad pärast 30 päeva ilma eduka värskendamiseta. Valikuline `scope` võib antud õigusi kitsendada. `offline_access` on alati kaasatud ja värskendustokenid väljastatakse alati. Esialgne päring ilma `scope`-ita annab ainult `offline_access`, seega peaksid kliendid taotlema vajalikke õigusi. Koodi taaskasutamine ja roteeritud värskendustokeni taaskasutamine tühistavad kogu autoriseerimise. Serialiseeri värskendamised kliendi sees; edukalt vahetatud mandaadi uuesti esitamine ei ole turvaline uuestiproovimise strateegia. Ühenduse katkestamiseks saada `token` ja `client_id` päringule `POST /v1/oauth/revoke`. Kummagi tokeni tühistamine tühistab selle autoriseerimise, sealhulgas kõik sellest väljastatud tokenid. Tundmatu token tagastab edu, avaldamata, kas see eksisteerib. Töölaua seansid saavad loetleda oma autoriseerimisi päringuga `GET /v1/oauth/grants` ja tühistada ühe päringuga `DELETE /v1/oauth/grants/`, kus `X-ThunderPhone-Org` valib organisatsiooni. ### Seadme autoriseerimine Seadme autoriseerimine on piiratud eelregistreeritud klientidega; dünaamiliselt registreeritud kliendid saavad vastuseks `unauthorized_client`. Eelregistreeritud avalik klient `thunderphone-cli` toetab seadme autoriseerimist ja värskendamist. Saada `client_id=thunderphone-cli` ja `scope` päringule `POST /v1/oauth/device/code`. Kuvage kasutajale `user_code` ja `verification_uri` või ava `verification_uri_complete`. Küsitle tokeni lõpp-punkti parameetritega `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` ja `device_code`, oodates vähemalt tagastatud `interval` väärtuse (5 sekundit). Jätka väärtuse `authorization_pending` korral. Väärtuse `slow_down` korral kasuta iga järgmise päringu jaoks vastuses tagastatud uut `interval` väärtust, mida suurendatakse 5 sekundi võrra. Peatu väärtuste `access_denied`, `expired_token` või mis tahes muu vea korral. Ära kunagi kinnita seadmekoodi automaatselt. Eelregistreeritud klient `thunderphone-mcp` aktsepteerib aadresse `http://127.0.0.1/callback` ja `http://localhost/callback` mis tahes pordil. Skeem, host, tee ja päring peavad vastama; tokenivahetus peab kasutama autoriseerimisest saadud täpset ümbersuunamise URI-d, sealhulgas porti. Dünaamiliselt registreeritud kliendid nõuavad ümbersuunamise URI täpset vastavust, sealhulgas porti. Registreeri dünaamiliselt teine tagasihelistamine, kui vajad muud teed. ### Konto identiteedi ja tööruumi domeeni kontrollid Taotle nii `openid email` kui ka toimingu ulatusi, mida sinu klient vajab. Kutsu tuvastatud `userinfo_endpoint` (`GET /v1/oauth/userinfo`) juurdepääsutokeniga Bearer-päises. Edukas vastus sisaldab: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` `sub` on stabiilne kasutajaidentifikaator; `org_id` on nõusoleku ajal valitud organisatsioon. Lõpp-punkt nõuab mõlemat identiteedi ulatust ja tagastab `403`, kui kumbki puudub. Kui kontol puudub kinnitatud e-posti profiil, tagastab see `403` koos väärtusega `error=access_denied`, selle asemel et väita, et kinnitamata e-post on usaldusväärne. Kehtetud, aegunud, tühistatud või vale sihtrühmaga tokenid tagastavad `401`. Inimseansi tokenid ja organisatsiooni API-võtmed ei saa userinfo lõpp-punkti kutsuda. ID-tokenit ei väljastata. ## Saadaolevad õigused | Rühm | Õigused | | --- | --- | | Häälagendid ja häälagentide import | `agents:read`, `agents:write` | | Kõned | `calls:read`, `calls:write` | | Telefoninumbrid ja VoIP | `numbers:read`, `numbers:write` | | Teadmised | `knowledge:read`, `knowledge:write` | | Kampaaniad | `campaigns:read`, `campaigns:write` | | Integratsioonid, veebikonksu lõpp-punktid, MCP-serverid | `integrations:read`, `integrations:write` | | Hääled | `voices:read` | | Testistsenaariumid, testikäivitused, valideerimine | `testing:read`, `testing:write` | | Arveldamine | `billing:read` | | Konto identiteet ja kinnitatud e-post | `openid`, `email` (mõlemad on userinfo jaoks nõutud) | | Püsiv ühendus | `offline_access` (alati kaasatud) | GET, HEAD ja OPTIONS kasutavad lugemisõigusi; muud meetodid kasutavad kirjutamisõigusi. Häälte ja arveldamise muutmistoimingud pole OAuthi kaudu saadaval; `POST /v1/voices/preview` kasutab õigust `voices:read`, sest see eelvaatab häält selle konfiguratsiooni muutmata. MCP-tööriistad jõustavad nende aluseks oleva REST-toimingu õigust. Organisatsioonidevahelised ülekanded keelatakse isegi siis, kui volitav kasutaja kuulub mõlemasse organisatsiooni. Muud API-rühmad, sealhulgas API-võtmete haldus ja kasutajakonto seaded, pole OAuthi kaudu saadaval. Puuduv õigus REST-toimingu jaoks tagastab `403` koos väärtusega `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Kehtetud või aegunud juurdepääsuload tagastavad `401`. ### MCP-tööriistade autentimissignaalid Iga tööriist asukohas `tools/list` sisaldab väärtust `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]` koos selle tööriista REST-toimingu õigusega. Avalikud dokumentatsioonitööriistad kasutavad tühja õiguste loendit ja nõuavad siiski autentitud ühendust. Kehtiv luba, millel puudub tööriista õigus, saab HTTP `200` koos JSON-RPC `result`-iga, mis sisaldab väärtust `isError: true`, selgitavat teksti väljal `content` ning `_meta["mcp/www_authenticate"]`. Viimane on massiiv, mis sisaldab Beareri väljakutset väärtustega `resource_metadata`, `error="insufficient_scope"`, `error_description` ja nõutud `scope`. Tööriista ei käivitata. Kasuta seda väljakutset laiendatud nõusoleku taotlemiseks. Puuduv või kehtetu autentimine tagastab jätkuvalt HTTP `401` koos `WWW-Authenticate`-iga; RESTi õiguste tõrked tagastavad jätkuvalt HTTP `403`. ## Mandaatide säilitamine API käivitab `python manage.py oauth_cleanup` iga tunni järel eeltootmises ja tootmises. See eemaldab aegunud autoriseerimistaotlused ja seadmekoodid. Aegunud juurdepääsulube, autoriseerimiskoode ja värskendusloa räsi eemaldatakse alles pärast nende volituse tühistamist või kogu perekonna kehtetuks muutumist. Kasutatud räsid säilitatakse seni, kuni perekonnal on kasutatav värskendusluba, autoriseerimiskood, heakskiidetud seadmekood või juurdepääsuluba, et puhastamine ei saaks korduskasutuse tuvastamist keelata.