Yhdistä OAuthilla

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:

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:

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

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

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

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

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