--- title: "Yhdistä OAuthilla" description: "Valtuuta MCP-asiakkaat ja ThunderPhone CLI ilman API-avaimen jakamista." --- OAuthin avulla sovellus voi muodostaa yhteyden yhteen ThunderPhone-organisaatioon hyväksymilläsi oikeuksilla. Hakemistoklienttien tulee käyttää OAuthia oletusarvoisesti. Organisaation API-avaimet ovat edelleen käytettävissä asiakkaille, jotka edellyttävät manuaalisesti määritettyä Bearer-tunnusta. ## Hyväksy yhteys Aloita yhteyden muodostaminen MCP-asiakkaassasi. Kirjaudu sisään ThunderPhoneen, tarkista sovelluksen nimi ja pyydetyt oikeudet, valitse organisaatio ja valitse **Hyväksy**. Valitse **Hylkää**, jos et aloittanut yhteyden muodostamista tai et luota sovellukseen. Sovellusten nimet toimittavat niiden kehittäjät, eivätkä ne ole vahvistusmerkki. Lukuoikeudet antavat pääsyn nimettyihin tietoihin, mukaan lukien tallenteisiin ja transkriptioihin, kun `calls:read` pyydetään. Kirjoitusoikeudet voivat muuttaa tai poistaa resursseja; puheluista, kampanjoista, puhelinnumeroiden ostoista ja käyttöönotosta voi aiheutua kustannuksia tai vaikutuksia tuotantoympäristöön. Organisaatioroolisi on edelleen voimassa. CLI-yhteyttä varten avaa päätteessä näkyvä vahvistuslinkki, vertaa kahdeksanmerkkistä koodia, valitse organisaatiosi ja hyväksy yhteys. Pelkkä linkin avaaminen ei myönnä käyttöoikeutta. Koodit vanhenevat 15 minuutin kuluttua. ## Katkaise sovelluksen yhteys Avaa hallintapaneelissa **Organisaatio → API-avaimet → Valtuutetut sovellukset** ja valitse **Peruuta**. Tämä peruuttaa valitsemasi valtuutuksen nykyisessä organisaatiossa, mukaan lukien sen käyttö- ja päivitystunnukset. Muodosta yhteys uudelleen sovelluksesta, jos haluat valtuuttaa sen uudelleen. ## MCP-asiakkaiden metatietojen löytäminen Käytä palvelimen URL-osoitetta `https://api.thunderphone.com/v1/mcp`. Pyyntö ilman kelvollista todennusta saa vastauksen `401`, jossa on: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Nouda tämä asiakirja ja nouda sitten valtuutuspalvelimen metatiedot osoitteesta `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Resurssin metatiedot ovat saatavilla myös osoitteessa `/.well-known/oauth-protected-resource/v1/mcp`. Käytä palautettuja päätepisteitä niiden muodostamisen sijaan. Resurssitunniste on `https://api.thunderphone.com/v1/mcp`. Palvelin tukee valtuutuskoodia **S256 PKCE**:llä, kiertäviä päivitystunnuksia, julkista dynaamista asiakasrekisteröintiä, mitätöintiä ja laitevaltuutuksen myöntämistä. Asiakassalaisuuksia tai implisiittisiä valtuutuksia ei ole. OpenID-löytäminen on myös saatavilla osoitteessa `/.well-known/openid-configuration`; se sisältää samat valtuutuspalvelimen kentät sekä `subject_types_supported: ["public"]` ja userinfo-päätepisteen. ID-tunnuksia ja Client ID Metadata Documents (CIMD) -asiakirjoja ei tueta. ### Rekisteröi julkinen asiakas Lähetä JSON-objekti osoitteeseen `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"] } ``` Tallenna palautettu `client_id`. Uudelleenohjausten on käytettävä HTTPS:ää tai HTTP:tä osoitteessa `127.0.0.1` tai `localhost`. Rekisteröi täsmällinen callback-URI, mukaan lukien sen portti ja polku. Fragmentit ja upotetut tunnistetiedot hylätään. Valinnaisten `client_uri`- ja `logo_uri`-arvojen on käytettävä HTTPS:ää; ThunderPhone ei nouda niitä rekisteröinnin aikana. Rekisteröinti on nopeusrajoitettu. Rekisteröidyt asiakkaat eivät vanhene ja pysyvät rekisteröityinä, kun yhteys mitätöidään. HTTPS-callbackeihin kuuluvat `https://chatgpt.com/connector/oauth/` ja `https://chatgpt.com/connector_platform_oauth_redirect`. Kukin yhteys voi rekisteröidä oman asiakkaansa. ### Valtuutuskoodi Avaa löydetty valtuutuspäätepiste käyttäen arvoja `client_id`, täsmällinen rekisteröity `redirect_uri`, `response_type=code`, satunnainen `state`, `scope`, `code_challenge`, `code_challenge_method=S256` ja `resource=https://api.thunderphone.com/v1/mcp`. Laske haaste tuoreen, suuren entropian PKCE-varmentajan ilman täytettä base64url-koodatusta SHA-256-tiivisteestä. Tarkista palautetut `state` ja `iss` ennen koodin vaihtamista. Jokainen valtuutusvastaus, myös hylkäys- ja protokollavirheet, tunnistaa myöntäjän arvolla `iss`, joka vastaa täsmälleen löydettyä `issuer`-arvoa. Virheellinen asiakas tai callback palauttaa virheen paikallisesti ilman uudelleenohjausta kyseiseen callbackiin. Vaihda osoitteessa `POST /v1/oauth/token` lomakekoodausta käyttäen (myös JSON hyväksytään): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` Valinnainen `resource`-parametri hyväksytään sekä valtuutus- että tunnuspyynnöissä, mukaan lukien päivitys- ja laitevaihdot. Kun se jätetään pois, oletusarvona käytetään löydettyä MCP-resurssia. Kun se annetaan, sen on vastattava täsmälleen kyseistä resurssia; muut arvot palauttavat `invalid_target`. Käyttöoikeustunnuksissa on kyseinen yleisö, ja MCP hylkää tunnukset, joiden yleisö puuttuu tai on erilainen, vastauksella `401` ja löytämishaasteella. Valtuutuspyynnöt ja -koodit vanhenevat 10 minuutin kuluttua. Jokainen tunnusvastaus sisältää arvot `access_token`, `token_type` (`Bearer`), `expires_in` (oletusarvoisesti 3600 sekuntia), `refresh_token`, `scope`, `organization_id` ja `organization_name`. Lähetä käyttöoikeustunnukset vain `Authorization: Bearer` -otsakkeen kautta. Älä koskaan lisää tunnuksia URL-osoitteisiin, lokeihin, versionhallintaan tai chattiin. ### Päivitä ja mitätöi Päivitä käyttämällä arvoja `grant_type=refresh_token`, `client_id`, `refresh_token` ja `resource` tunnuspäätepisteessä. Tallenna uusi päivitystunnus atomisesti ja lopeta vanhan käyttäminen. Päivitystunnukset vanhenevat 30 päivän kuluttua ilman onnistunutta päivitystä. Valinnainen `scope` voi rajata myönnettyjä käyttöoikeuksia. `offline_access` sisällytetään aina, ja päivitystunnuksia myönnetään aina. Alkuperäinen pyyntö ilman `scope`-arvoa myöntää vain `offline_access`-käyttöoikeuden, joten asiakkaiden on pyydettävä tarvitsemansa käyttöoikeudet. Koodin uudelleenkäyttö ja kiertävän päivitystunnuksen uudelleenkäyttö mitätöivät koko valtuutuksen. Sarjallista päivitykset asiakkaan sisällä; onnistuneesti vaihdetun tunnistetiedon toistaminen ei ole turvallinen uudelleenyritysstrategia. Katkaise yhteys lähettämällä `token` ja `client_id` osoitteeseen `POST /v1/oauth/revoke`. Kumman tahansa tunnuksen mitätöinti mitätöi sen valtuutuksen, mukaan lukien kaikki siitä myönnetyt tunnukset. Tuntematon tunnus palauttaa onnistumisen paljastamatta, onko se olemassa. Hallintapaneelin istunnot voivat listata omat valtuutuksensa osoitteessa `GET /v1/oauth/grants` ja mitätöidä yhden osoitteessa `DELETE /v1/oauth/grants/`, jolloin `X-ThunderPhone-Org` valitsee organisaation. ### Laitevaltuutus Laitevaltuutus on rajoitettu ennalta rekisteröityihin asiakkaisiin; dynaamisesti rekisteröidyt asiakkaat saavat vastauksen `unauthorized_client`. Ennalta rekisteröity julkinen asiakas `thunderphone-cli` tukee laitevaltuutusta ja päivitystä. Lähetä `client_id=thunderphone-cli` ja `scope` osoitteeseen `POST /v1/oauth/device/code`. Näytä käyttäjälle `user_code` ja `verification_uri` tai avaa `verification_uri_complete`. Tee kysely tunnuspäätepisteeseen arvoilla `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` ja `device_code` odottaen vähintään palautetun `interval`-ajan (5 sekuntia). Jatka vastauksella `authorization_pending`. Käytä vastauksessa palautettua uutta `interval`-arvoa (kasvaa 5 sekunnilla) jokaisessa seuraavassa pyynnössä, kun saat vastauksen `slow_down`. Lopeta vastauksella `access_denied`, `expired_token` tai millä tahansa muulla virheellä. Älä koskaan hyväksy laitekoodia automaattisesti. Ennalta rekisteröity asiakas `thunderphone-mcp` hyväksyy osoitteet `http://127.0.0.1/callback` ja `http://localhost/callback` millä tahansa portilla. Protokollan, isännän, polun ja kyselyparametrien on vastattava; tunnusvaihdossa on käytettävä valtuutuksesta saatua täsmällistä uudelleenohjaus-URI:a, mukaan lukien portti. Dynaamisesti rekisteröidyt asiakkaat edellyttävät täsmällistä uudelleenohjaus-URI:n vastaavuutta, mukaan lukien portti. Rekisteröi toinen callback dynaamisesti, jos tarvitset toisen polun. ### Tilin identiteetin ja työtilan verkkotunnuksen tarkistukset Pyydä sekä `openid email` että asiakkaasi tarvitsemat toimintokohtaiset käyttöoikeusalueet. Kutsu löydettyä `userinfo_endpoint`-päätepistettä (`GET /v1/oauth/userinfo`) käyttöoikeustunnuksella Bearer-otsakkeessa. Onnistunut vastaus sisältää: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` `sub` on pysyvä käyttäjätunniste; `org_id` on suostumuksen aikana valittu organisaatio. Päätepiste edellyttää molempia identiteetin käyttöoikeusalueita ja palauttaa `403`, jos jompikumpi puuttuu. Se palauttaa `403`-vastauksen arvolla `error=access_denied`, jos tilillä ei ole vahvistettua sähköpostiprofiilia, sen sijaan että väittäisi vahvistamatonta sähköpostia luotetuksi. Virheelliset, vanhentuneet, mitätöidyt tai väärän yleisön tunnukset palauttavat `401`. Käyttäjäistuntotunnukset ja organisaation API-avaimet eivät voi kutsua userinfo-päätepistettä. ID-tunnusta ei myönnetä. ## Käytettävissä olevat käyttöoikeudet | Ryhmä | Käyttöoikeusalueet | | --- | --- | | Agentit ja agenttien tuonnit | `agents:read`, `agents:write` | | Puhelut | `calls:read`, `calls:write` | | Puhelinnumerot, estetyt soittajat ja VoIP | `numbers:read`, `numbers:write` | | Tietämys | `knowledge:read`, `knowledge:write` | | Kampanjat | `campaigns:read`, `campaigns:write` | | Integraatiot, webhook-päätepisteet, MCP-palvelimet | `integrations:read`, `integrations:write` | | Äänet | `voices:read` | | Testiskenaariot, testiajot, validointi | `testing:read`, `testing:write` | | Laskutus | `billing:read` | | Tilin identiteetti ja vahvistettu sähköposti | `openid`, `email` (molemmat vaaditaan userinfoa varten) | | Pysyvä yhteys | `offline_access` (sisältyy aina) | GET, HEAD ja OPTIONS käyttävät lukualueita; muut menetelmät käyttävät kirjoitusalueita. Ääni- ja laskutusmuutokset eivät ole käytettävissä OAuthin kautta; `POST /v1/voices/preview` käyttää `voices:read`-aluetta, koska se esikatselee ääntä muuttamatta sen määritystä. MCP-työkalut noudattavat niiden taustalla olevan REST-toiminnon käyttöaluetta. Organisaatioiden väliset siirrot estetään, vaikka valtuuttava käyttäjä kuuluisi molempiin organisaatioihin. Muut API-ryhmät, mukaan lukien API-avainten hallinta ja henkilötilin asetukset, eivät ole käytettävissä OAuthin kautta. Jos REST-toiminnolta puuttuu käyttöoikeus, se palauttaa `403`-vastauksen, jossa on `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Virheelliset tai vanhentuneet käyttöoikeustunnukset palauttavat `401`. ### MCP-työkalujen todennussignaalit Jokainen `tools/list`-kohdan työkalu sisältää `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]`, jossa on kyseisen työkalun REST-toiminnon käyttöalue. Julkiset dokumentaatiotyökalut käyttävät tyhjää käyttöalueluetteloa ja vaativat silti todennetun yhteyden. Kelvollinen tunnus, jolta puuttuu työkalun käyttöalue, vastaanottaa HTTP `200` -vastauksen, jossa JSON-RPC-`result` sisältää `isError: true`-, `content`-selitystekstin ja `_meta["mcp/www_authenticate"]`-kentän. Jälkimmäinen on taulukko, joka sisältää Bearer-haasteen, jossa ovat `resource_metadata`, `error="insufficient_scope"`, `error_description` ja vaadittu `scope`. Työkalua ei suoriteta. Käytä tätä haastetta laajennetun suostumuksen pyytämiseen. Puuttuva tai virheellinen todennus palauttaa edelleen HTTP `401` -vastauksen ja `WWW-Authenticate`-otsakkeen; REST-käyttöaluevirheet palauttavat edelleen HTTP `403`. ## Tunnistetietojen säilyttäminen API suorittaa `python manage.py oauth_cleanup` tunnin välein esituotanto- ja tuotantoympäristöissä. Se poistaa vanhentuneet valtuutuspyynnöt ja laitekoodeja. Vanhentuneet käyttöoikeustunnukset, valtuutuskoodit ja päivitystunnusten tiivisteet karsitaan vasta, kun niiden myöntö on peruutettu tai koko tunnusperhe ei ole enää käytettävissä. Käytetyt tiivisteet säilytetään, kun tunnusperheellä on käytettävissä oleva päivitystunnus, valtuutuskoodi, hyväksytty laitekoodi tai käyttöoikeustunnus, joten siivous ei voi poistaa uudelleentoiston tunnistusta käytöstä.