Open in

Povežite se z OAuth

Avtorizirajte odjemalce MCP in ThunderPhone CLI brez deljenja ključa API.

OAuth aplikaciji omogoča povezavo z eno organizacijo ThunderPhone z dovoljenji, ki jih odobrite. Odjemalci imenika naj privzeto uporabljajo OAuth. Organizacijski ključi API ostajajo na voljo za odjemalce, ki zahtevajo ročno konfiguriran žeton Bearer.

Odobrite povezavo

Začnite povezavo v svojem odjemalcu MCP. Prijavite se v ThunderPhone, preverite ime aplikacije in zahtevana dovoljenja, izberite organizacijo ter izberite Odobrite. Če povezave niste začeli vi ali aplikaciji ne zaupate, izberite Zavrnite. Imena aplikacij navedejo njihovi razvijalci in niso znak preverjenosti.

Dovoljenja za branje omogočajo dostop do navedenih podatkov, vključno s posnetki in prepisi, kadar je zahtevano calls:read. Dovoljenja za pisanje lahko spremenijo ali izbrišejo vire; klici, kampanje, nakupi telefonskih številk in uvedbe lahko povzročijo stroške ali vplivajo na produkcijo. Vaša vloga v organizaciji še vedno velja.

Za povezavo CLI odprite povezavo za preverjanje, prikazano v terminalu, primerjajte osemznakovno kodo, izberite organizacijo in odobrite povezavo. Že samo odprtje povezave ne odobri dostopa. Kode potečejo po 15 minutah.

Prekinite povezavo z aplikacijo

Na nadzorni plošči odprite Organizacija → Ključi API → Pooblaščene aplikacije in izberite Prekličite. S tem prekličete izbrano avtorizacijo za trenutno organizacijo, vključno z njenima žetonoma za dostop in osvežitev. Če jo želite znova pooblastiti, se znova povežite iz aplikacije.

Odkrivanje za odjemalce MCP

Uporabite URL strežnika https://api.thunderphone.com/v1/mcp. Zahteva brez veljavne avtentikacije prejme 401 z:

WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource"

Pridobite ta dokument, nato pa pridobite metapodatke avtorizacijskega strežnika na https://api.thunderphone.com/.well-known/oauth-authorization-server. Metapodatki vira so na voljo tudi na /.well-known/oauth-protected-resource/v1/mcp. Uporabite vrnjene končne točke, namesto da jih sestavljate sami. Identifikator vira je https://api.thunderphone.com/v1/mcp.

Strežnik podpira avtorizacijsko kodo s S256 PKCE, rotirajoče žetone za osvežitev, javno dinamično registracijo odjemalcev, preklic in dodelitev avtorizacije napravi. Skrivnosti odjemalca in implicitne dodelitve niso na voljo. Odkrivanje OpenID je na voljo tudi na /.well-known/openid-configuration; vključuje ista polja avtorizacijskega strežnika ter subject_types_supported: ["public"] in končno točko userinfo. Žetoni ID in dokumenti metapodatkov ID-ja odjemalca (CIMD) niso podprti.

Registracija javnega odjemalca

Pošljite JSON na 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"]
}

Shranite vrnjeni client_id. Preusmeritve morajo uporabljati HTTPS ali HTTP na 127.0.0.1 oziroma localhost. Registrirajte natančen URI povratnega klica, vključno z vrati in potjo. Fragmenti in vdelane poverilnice so zavrnjeni. Izbirna client_uri in logo_uri morata uporabljati HTTPS; ThunderPhone ju med registracijo ne pridobiva. Registracija je omejena s številom zahtev. Registrirani odjemalci ne potečejo in ostanejo registrirani tudi ob preklicu povezave. Povratni klici HTTPS vključujejo https://chatgpt.com/connector/oauth/<id> in https://chatgpt.com/connector_platform_oauth_redirect. Vsaka povezava lahko registrira svojega odjemalca.

Avtorizacijska koda

Odprite odkrito končno točko za avtorizacijo z client_id, natančno registriranim redirect_uri, response_type=code, naključnim state, scope, code_challenge, code_challenge_method=S256 in resource=https://api.thunderphone.com/v1/mcp. Izziv izračunajte kot neoblazinjen izvleček SHA-256 v zapisu base64url iz novega preverjevalnika PKCE z visoko entropijo. Pred zamenjavo kode preverite vrnjena state in iss. Vsak odziv avtorizacije, vključno z zavrnitvijo in napakami protokola, identificira izdajatelja z iss, ki se natančno ujema z odkritim issuer. Napake za neveljavnega odjemalca ali povratni klic so vrnjene lokalno brez preusmeritve na ta povratni klic.

Zamenjajte na POST /v1/oauth/token z uporabo kodiranja obrazca (sprejet je tudi JSON):

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

Izbirni parameter resource je sprejet pri zahtevah za avtorizacijo in žetone (vključno z osvežitvami in zamenjavami za naprave). Če ni naveden, je privzeto nastavljen na odkriti vir MCP. Če je naveden, se mora natančno ujemati s tem virom; druge vrednosti vrnejo invalid_target. Dostopni žetoni vsebujejo to ciljno skupino, MCP pa zavrne žetone z manjkajočo ali drugačno ciljno skupino z 401 in izzivom za odkrivanje.

Zahteve za avtorizacijo in kode potečejo po 10 minutah. Vsak odziv žetona vsebuje access_token, token_type (Bearer), expires_in (privzeto 3600 sekund), refresh_token, scope, organization_id in organization_name. Dostopne žetone pošiljajte samo prek glave Authorization: Bearer. Žetonov nikoli ne vstavljajte v URL-je, dnevnike, nadzor izvorne kode ali klepet.

Osvežitev in preklic

Osvežite z grant_type=refresh_token, client_id, refresh_token in resource na končni točki za žetone. Novi žeton za osvežitev shranite atomsko in prenehajte uporabljati starega. Žetoni za osvežitev potečejo po 30 dneh brez uspešne osvežitve. Izbirni scope lahko zoži dodeljena dovoljenja. offline_access je vedno vključen in žetoni za osvežitev so vedno izdani. Začetna zahteva brez scope dodeli samo offline_access, zato naj odjemalci zahtevajo dovoljenja, ki jih potrebujejo.

Ponovna uporaba kode in ponovna uporaba rotiranega žetona za osvežitev prekličeta celotno avtorizacijo. Osvežitve znotraj odjemalca izvajajte zaporedno; ponovno predvajanje uspešno zamenjane poverilnice ni varna strategija za ponovni poskus.

Za prekinitev povezave pošljite token in client_id na POST /v1/oauth/revoke. Preklic katerega koli žetona prekliče njegovo avtorizacijo, vključno z vsemi žetoni, izdanimi iz njega. Neznan žeton vrne uspeh, ne da bi razkril, ali obstaja. Seje nadzorne plošče lahko navedejo lastne avtorizacije na GET /v1/oauth/grants in prekličejo posamezno na DELETE /v1/oauth/grants/<id>, pri čemer X-ThunderPhone-Org izbere organizacijo.

Avtorizacija naprave

Avtorizacija naprave je omejena na vnaprej registrirane odjemalce; dinamično registrirani odjemalci prejmejo unauthorized_client. Vnaprej registrirani javni odjemalec thunderphone-cli podpira avtorizacijo naprave in osvežitev. Pošljite client_id=thunderphone-cli in scope na POST /v1/oauth/device/code. Uporabniku prikažite user_code in verification_uri ali odprite verification_uri_complete.

Anketirajte končno točko za žetone z grant_type=urn:ietf:params:oauth:grant-type:device_code, client_id in device_code ter počakajte vsaj vrnjeni interval (5 sekund). Nadaljujte pri authorization_pending. Pri slow_down uporabite novi interval, vrnjen v odzivu (povečan za 5 sekund), za vsako naslednjo zahtevo. Ustavite se pri access_denied, expired_token ali kateri koli drugi napaki. Kode naprave nikoli ne odobrite samodejno.

Vnaprej registrirani odjemalec thunderphone-mcp sprejema http://127.0.0.1/callback in http://localhost/callback na katerih koli vratih. Shema, gostitelj, pot in poizvedba se morajo ujemati; zamenjava žetona mora uporabiti natančen URI preusmeritve (vključno z vrati) iz avtorizacije. Dinamično registrirani odjemalci zahtevajo natančno ujemanje URI-ja preusmeritve, vključno z vrati. Če potrebujete drugo pot, dinamično registrirajte drug povratni klic.

Preverjanje identitete računa in domene delovnega prostora

Zahtevajte oba obsega openid email skupaj z obsegi operacij, ki jih potrebuje vaš odjemalec. Pokličite odkrito userinfo_endpoint (GET /v1/oauth/userinfo) z dostopnim žetonom v glavi Bearer. Uspešen odziv vsebuje:

{
  "sub": "123",
  "email": "person@example.com",
  "email_verified": true,
  "name": "Example User",
  "org_id": 456
}

sub je stabilen identifikator uporabnika; org_id je organizacija, izbrana med privolitvijo. Končna točka zahteva oba obsega identitete in vrne 403, če kateri koli manjka. Vrne 403 z error=access_denied, če račun nima profila s preverjenim e-poštnim naslovom, namesto da bi trdila, da je nepreverjen e-poštni naslov zaupanja vreden. Neveljavni, potekli, preklicani žetoni ali žetoni z napačno ciljno skupino vrnejo 401. Žetoni človeških sej in ključi API organizacije ne morejo klicati userinfo. Žeton ID ni izdan.

Razpoložljiva dovoljenja

Družina	Obsegi
Agenti in uvozi agentov	`agents:read`, `agents:write`
Klici	`calls:read`, `calls:write`
Telefonske številke in VoIP	`numbers:read`, `numbers:write`
Znanje	`knowledge:read`, `knowledge:write`
Kampanje	`campaigns:read`, `campaigns:write`
Integracije, končne točke webhookov, strežniki MCP	`integrations:read`, `integrations:write`
Glasovi	`voices:read`
Preskusni scenariji, preskusni zagoni, preverjanje veljavnosti	`testing:read`, `testing:write`
Obračunavanje	`billing:read`
Identiteta računa in potrjen e-poštni naslov	`openid`, `email` (oba sta zahtevana za userinfo)
Trajna povezava	`offline_access` (vedno vključeno)

GET, HEAD in OPTIONS uporabljajo obsege branja; druge metode uporabljajo obsege pisanja. Spremembe glasov in obračunavanja prek OAuth niso na voljo; POST /v1/voices/preview uporablja voices:read, ker prikaže predogled glasu, ne da bi spremenil njegovo konfiguracijo. Orodja MCP uveljavljajo obseg svoje osnovne operacije REST. Prenosi med organizacijami so zavrnjeni tudi, kadar uporabnik, ki odobri dostop, pripada obema organizacijama. Druge družine API-jev, vključno z upravljanjem ključev API in nastavitvami uporabniškega računa, prek OAuth niso na voljo. Manjkajoče dovoljenje pri operaciji REST vrne 403 z WWW-Authenticate: Bearer error="insufficient_scope", scope="...". Neveljavni ali potekli žetoni za dostop vrnejo 401.

Signali preverjanja pristnosti orodij MCP

Vsako orodje v tools/list vključuje securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}] z obsegom operacije REST tega orodja. Javna dokumentacijska orodja uporabljajo prazen seznam obsegov in še vedno zahtevajo avtenticirano povezavo.

Veljaven žeton brez obsega orodja prejme HTTP 200 z JSON-RPC result, ki vsebuje isError: true, pojasnjevalno besedilo v content in _meta["mcp/www_authenticate"]. Slednje je polje, ki vsebuje izziv Bearer z resource_metadata, error="insufficient_scope", error_description in zahtevanim scope. Orodje se ne izvede. Ta izziv uporabite za zahtevo po razširjenem soglasju. Manjkajoče ali neveljavno preverjanje pristnosti še naprej vrača HTTP 401 z WWW-Authenticate; napake obsegov REST še naprej vračajo HTTP 403.

Hramba poverilnic

API vsako uro v predprodukcijskem in produkcijskem okolju zažene python manage.py oauth_cleanup. Odstrani potekle zahteve za avtorizacijo in kode naprav. Potekli žetoni za dostop, avtorizacijske kode in zgoščene vrednosti žetonov za osvežitev se odstranijo šele po preklicu njihove dodelitve ali ko celotna družina ni več veljavna. Uporabljene zgoščene vrednosti se hranijo, dokler ima družina uporaben žeton za osvežitev, avtorizacijsko kodo, odobreno kodo naprave ali žeton za dostop, zato čiščenje ne more onemogočiti zaznavanja ponovne uporabe.