--- title: "Savienojiet ar OAuth" description: "Autorizējiet MCP klientus un ThunderPhone CLI, nekopīgojot API atslēgu." --- OAuth ļauj lietotnei izveidot savienojumu ar vienu ThunderPhone organizāciju, izmantojot jūsu apstiprinātās atļaujas. Direktoriju klientiem pēc noklusējuma jāizmanto OAuth. Organizācijas API atslēgas joprojām ir pieejamas klientiem, kuriem nepieciešams manuāli konfigurēts Bearer marķieris. ## Apstipriniet savienojumu Sāciet savienojumu savā MCP klientā. Pierakstieties ThunderPhone, pārbaudiet lietotnes nosaukumu un pieprasītās atļaujas, izvēlieties organizāciju un atlasiet **Apstiprināt**. Atlasiet **Noraidīt**, ja savienojumu neuzsācāt jūs vai neuzticaties lietotnei. Lietotņu nosaukumus norāda to izstrādātāji, un tie nav verifikācijas apliecinājums. Lasīšanas atļaujas nodrošina piekļuvi norādītajiem datiem, tostarp ierakstiem un transkripcijām, ja tiek pieprasīta `calls:read` atļauja. Rakstīšanas atļaujas var mainīt vai dzēst resursus; zvani, kampaņas, tālruņa numuru iegādes un izvietošanas var radīt izmaksas vai ietekmēt produkcijas vidi. Jūsu organizācijas loma joprojām tiek piemērota. CLI savienojumam atveriet terminālī parādīto verifikācijas saiti, salīdziniet astoņu rakstzīmju kodu, atlasiet savu organizāciju un apstipriniet. Tikai saites atvēršana nepiešķir piekļuvi. Kodu derīguma termiņš beidzas pēc 15 minūtēm. ## Atvienojiet lietotni Informācijas panelī atveriet **Organizācija → API atslēgas → Autorizētās lietotnes** un izvēlieties **Atsaukt**. Tādējādi tiek atsaukta jūsu atlasītā autorizācija pašreizējai organizācijai, tostarp tās piekļuves un atsvaidzināšanas marķieri. Ja vēlaties lietotni autorizēt vēlreiz, atkārtoti izveidojiet savienojumu no lietotnes. ## MCP klientu atklāšana Izmantojiet servera URL `https://api.thunderphone.com/v1/mcp`. Pieprasījums bez derīgas autentifikācijas saņem `401` ar: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Iegūstiet šo dokumentu, pēc tam iegūstiet autorizācijas servera metadatus vietnē `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Resursa metadati ir pieejami arī vietnē `/.well-known/oauth-protected-resource/v1/mcp`. Izmantojiet atgrieztos galapunktus, nevis veidojiet tos manuāli. Resursa identifikators ir `https://api.thunderphone.com/v1/mcp`. Serveris atbalsta autorizācijas kodu ar **S256 PKCE**, rotējošus atsvaidzināšanas marķierus, publisku dinamisku klientu reģistrāciju, atsaukšanu un ierīces autorizācijas piešķīrumu. Klientu noslēpumu vai netiešo piešķīrumu nav. OpenID atklāšana ir pieejama arī vietnē `/.well-known/openid-configuration`; tā ietver tos pašus autorizācijas servera laukus, kā arī `subject_types_supported: ["public"]` un lietotāja informācijas galapunktu. ID marķieri un klienta ID metadatu dokumenti (CIMD) netiek atbalstīti. ### Reģistrējiet publisku klientu Nosūtiet JSON uz `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"] } ``` Saglabājiet atgriezto `client_id`. Novirzīšanai jāizmanto HTTPS vai HTTP adresē `127.0.0.1` vai `localhost`. Reģistrējiet precīzu atzvanīšanas URI, ieskaitot tā portu un ceļu. Fragmenti un iegultas akreditācijas dati tiek noraidīti. Neobligātajiem `client_uri` un `logo_uri` jāizmanto HTTPS; ThunderPhone tos reģistrācijas laikā neiegūst. Reģistrācijai ir biežuma ierobežojums. Reģistrētajiem klientiem nav derīguma termiņa, un tie paliek reģistrēti, kad savienojums tiek atsaukts. HTTPS atzvanīšanas adreses ietver `https://chatgpt.com/connector/oauth/` un `https://chatgpt.com/connector_platform_oauth_redirect`. Katrs savienojums var reģistrēt savu klientu. ### Autorizācijas kods Atveriet atklāto autorizācijas galapunktu ar `client_id`, precīzu reģistrēto `redirect_uri`, `response_type=code`, nejaušu `state`, `scope`, `code_challenge`, `code_challenge_method=S256` un `resource=https://api.thunderphone.com/v1/mcp`. Aprēķiniet pārbaudes vērtību kā jauna augstas entropijas PKCE verificētāja SHA-256 jaucējvērtību base64url formātā bez polsterējuma. Pirms koda apmaiņas pārbaudiet atgrieztos `state` un `iss`. Katra autorizācijas atbilde, tostarp atteikumi un protokola kļūdas, identificē izdevēju ar `iss`, kas precīzi atbilst atklātajam `issuer`. Kļūdas nederīgam klientam vai atzvanīšanai tiek atgrieztas lokāli, nenovirzot uz šo atzvanīšanu. Veiciet apmaiņu vietnē `POST /v1/oauth/token`, izmantojot formas kodējumu (tiek pieņemts arī JSON): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` Neobligātais parametrs `resource` tiek pieņemts gan autorizācijas, gan marķieru pieprasījumos, tostarp atsvaidzināšanas un ierīces apmaiņās. Ja tas nav norādīts, pēc noklusējuma tiek izmantots atklātais MCP resurss. Ja tas ir norādīts, tam precīzi jāatbilst šim resursam; citas vērtības atgriež `invalid_target`. Piekļuves marķieros ir šī auditorija, un MCP noraida marķierus ar trūkstošu vai atšķirīgu auditoriju, atgriežot `401` un atklāšanas pārbaudi. Autorizācijas pieprasījumu un kodu derīguma termiņš beidzas pēc 10 minūtēm. Katrā marķiera atbildē ir `access_token`, `token_type` (`Bearer`), `expires_in` (pēc noklusējuma 3600 sekundes), `refresh_token`, `scope`, `organization_id` un `organization_name`. Sūtiet piekļuves marķierus tikai ar galveni `Authorization: Bearer`. Nekad neievietojiet marķierus URL adresēs, žurnālos, pirmkoda versiju pārvaldībā vai tērzēšanā. ### Atsvaidziniet un atsauciet Atsvaidziniet ar `grant_type=refresh_token`, `client_id`, `refresh_token` un `resource` marķieru galapunktā. Saglabājiet jauno atsvaidzināšanas marķieri atomāri un pārtrauciet izmantot veco. Atsvaidzināšanas marķieru derīguma termiņš beidzas pēc 30 dienām bez veiksmīgas atsvaidzināšanas. Neobligāts `scope` var sašaurināt piešķirtās atļaujas. `offline_access` vienmēr tiek iekļauts, un atsvaidzināšanas marķieri vienmēr tiek izsniegti. Sākotnējais pieprasījums bez `scope` piešķir tikai `offline_access`, tāpēc klientiem jāpieprasa nepieciešamās atļaujas. Koda atkārtota izmantošana un rotēta atsvaidzināšanas marķiera atkārtota izmantošana atsauc visu autorizāciju. Serializējiet atsvaidzināšanu viena klienta ietvaros; veiksmīgi apmainītu akreditācijas datu atkārtota izmantošana nav droša atkārtošanas stratēģija. Lai atvienotos, nosūtiet `token` un `client_id` uz `POST /v1/oauth/revoke`. Jebkura marķiera atsaukšana atsauc tā autorizāciju, tostarp visus no tā izsniegtos marķierus. Nezināms marķieris atgriež veiksmīgu rezultātu, neatklājot, vai tas pastāv. Informācijas paneļa sesijas var uzskaitīt savas autorizācijas vietnē `GET /v1/oauth/grants` un atsaukt vienu vietnē `DELETE /v1/oauth/grants/`, kur `X-ThunderPhone-Org` atlasa organizāciju. ### Ierīces autorizācija Ierīces autorizācija ir ierobežota ar iepriekš reģistrētiem klientiem; dinamiski reģistrēti klienti saņem `unauthorized_client`. Iepriekš reģistrētais publiskais klients `thunderphone-cli` atbalsta ierīces autorizāciju un atsvaidzināšanu. Nosūtiet `client_id=thunderphone-cli` un `scope` uz `POST /v1/oauth/device/code`. Parādiet lietotājam `user_code` un `verification_uri` vai atveriet `verification_uri_complete`. Aptaujājiet marķieru galapunktu ar `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` un `device_code`, gaidot vismaz atgriezto `interval` (5 sekundes). Turpiniet, saņemot `authorization_pending`. Saņemot `slow_down`, katram turpmākajam pieprasījumam izmantojiet atbildē atgriezto jauno `interval` (palielinātu par 5 sekundēm). Apturiet darbību, saņemot `access_denied`, `expired_token` vai jebkuru citu kļūdu. Nekad neapstipriniet ierīces kodu automātiski. Iepriekš reģistrētais klients `thunderphone-mcp` pieņem `http://127.0.0.1/callback` un `http://localhost/callback` jebkurā portā. Shēmai, resursdatoram, ceļam un vaicājumam jāatbilst; marķiera apmaiņā jāizmanto precīzs autorizācijas novirzīšanas URI, tostarp ports. Dinamiski reģistrētiem klientiem ir nepieciešama precīza novirzīšanas URI atbilstība, tostarp ports. Ja nepieciešams cits ceļš, dinamiski reģistrējiet citu atzvanīšanu. ### Konta identitātes un darbvietas domēna pārbaudes Pieprasiet gan `openid email`, gan darbības tvērumus, kas nepieciešami jūsu klientam. Izsauciet atklāto `userinfo_endpoint` (`GET /v1/oauth/userinfo`) ar piekļuves marķieri Bearer galvenē. Veiksmīgā atbildē ir: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` `sub` ir stabils lietotāja identifikators; `org_id` ir piekrišanas laikā atlasītā organizācija. Galapunktam ir nepieciešami abi identitātes tvērumi, un, ja kāda trūkst, tas atgriež `403`. Ja kontam nav verificēta e-pasta profila, tas atgriež `403` ar `error=access_denied`, nevis apgalvo, ka neverificēts e-pasts ir uzticams. Nederīgi, beigušies, atsaukti vai nepareizai auditorijai paredzēti marķieri atgriež `401`. Cilvēku sesiju marķieri un organizācijas API atslēgas nevar izsaukt userinfo. ID marķieris netiek izsniegts. ## Pieejamās atļaujas | Grupa | Tvērumi | | --- | --- | | Balss aģenti un balss aģentu importēšana | `agents:read`, `agents:write` | | Zvani | `calls:read`, `calls:write` | | Tālruņa numuri, bloķētie zvanītāji un VoIP | `numbers:read`, `numbers:write` | | Zināšanas | `knowledge:read`, `knowledge:write` | | Kampaņas | `campaigns:read`, `campaigns:write` | | Integrācijas, tīmekļa aizķeres galapunkti, MCP serveri | `integrations:read`, `integrations:write` | | Balsis | `voices:read` | | Testēšanas scenāriji, testu izpildes, validācija | `testing:read`, `testing:write` | | Norēķini | `billing:read` | | Konta identitāte un verificēta e-pasta adrese | `openid`, `email` (abi nepieciešami userinfo) | | Pastāvīgs savienojums | `offline_access` (vienmēr iekļauts) | GET, HEAD un OPTIONS izmanto lasīšanas tvērumus; citas metodes izmanto rakstīšanas tvērumus. Balss un norēķinu modificēšanas darbības nav pieejamas, izmantojot OAuth; `POST /v1/voices/preview` izmanto `voices:read`, jo tas ļauj priekšskatīt balsi, nemainot tās konfigurāciju. MCP rīki ievēro pamatā esošās REST darbības tvērumu. Pārsūtījumi starp organizācijām tiek noraidīti pat tad, ja autorizējošais lietotājs pieder abām organizācijām. Citas API kategorijas, tostarp API atslēgu pārvaldība un cilvēku kontu iestatījumi, nav pieejamas, izmantojot OAuth. Ja REST darbībai trūkst atļaujas, tiek atgriezts `403` ar `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Nederīgi vai beigušies piekļuves marķieri atgriež `401`. ### MCP rīku autentifikācijas signāli Katrs rīks pakotnē `tools/list` ietver `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]` ar šī rīka REST darbības tvērumu. Publiskie dokumentācijas rīki izmanto tukšu tvērumu sarakstu un joprojām pieprasa autentificētu savienojumu. Ja derīgam marķierim trūkst rīka tvēruma, tiek saņemta HTTP `200` atbilde ar JSON-RPC `result`, kas satur `isError: true`, paskaidrojošu tekstu laukā `content` un `_meta["mcp/www_authenticate"]`. Pēdējais ir masīvs ar Bearer autentifikācijas izaicinājumu, kurā ietverti `resource_metadata`, `error="insufficient_scope"`, `error_description` un nepieciešamais `scope`. Rīks netiek izpildīts. Izmantojiet šo izaicinājumu, lai pieprasītu paplašinātu piekrišanu. Ja autentifikācija nav pieejama vai nav derīga, joprojām tiek atgriezts HTTP `401` ar `WWW-Authenticate`; REST tvēruma kļūmes joprojām atgriež HTTP `403`. ## Akreditācijas datu glabāšana API starpvidē un produkcijas vidē katru stundu izpilda `python manage.py oauth_cleanup`. Tas noņem autorizācijas pieprasījumus un ierīču kodus, kuriem beidzies derīguma termiņš. Piekļuves marķieri, autorizācijas kodi un atsvaidzināšanas marķieru jaucējvērtības, kuriem beidzies derīguma termiņš, tiek dzēsti tikai pēc tam, kad to piešķīrums ir atsaukts vai visa saime vairs nav aktīva. Izmantotās jaucējvērtības tiek saglabātas, kamēr saimei ir izmantojams atsvaidzināšanas marķieris, autorizācijas kods, apstiprināts ierīces kods vai piekļuves marķieris, lai tīrīšana nevarētu atspējot atkārtotas izmantošanas noteikšanu.