Open in

Povežite se s OAuthom

Autorizirajte MCP klijente i ThunderPhone CLI bez dijeljenja API ključa.

OAuth omogućuje aplikaciji povezivanje s jednom organizacijom ThunderPhone s dozvolama koje odobrite. Klijenti direktorija trebali bi prema zadanim postavkama koristiti OAuth. Organizacijski API ključevi i dalje su dostupni za klijente kojima je potreban ručno konfiguriran Bearer token.

Odobrite povezivanje

Pokrenite povezivanje u svom MCP klijentu. Prijavite se u ThunderPhone, provjerite naziv aplikacije i zatražene dozvole, odaberite organizaciju i odaberite Odobri. Odaberite Odbij ako niste pokrenuli povezivanje ili ne vjerujete aplikaciji. Nazive aplikacija navode njihovi razvojni programeri i oni nisu oznaka provjere.

Dozvole za čitanje otkrivaju navedene podatke, uključujući snimke i prijepise kada se zatraži calls:read. Dozvole za pisanje mogu promijeniti ili izbrisati resurse; pozivi, kampanje, kupnje telefonskih brojeva i implementacije mogu uzrokovati troškove ili utjecati na produkciju. Vaša uloga u organizaciji i dalje vrijedi.

Za CLI povezivanje otvorite vezu za provjeru prikazanu u terminalu, usporedite osmeroznamenkasti kôd, odaberite organizaciju i odobrite povezivanje. Samo otvaranje veze ne odobrava pristup. Kôdovi istječu nakon 15 minuta.

Prekinite povezivanje aplikacije

Na nadzornoj ploči otvorite Organizacija → API ključevi → Ovlaštene aplikacije i odaberite Opozovi. Time se opoziva vaše odabrano ovlaštenje za trenutačnu organizaciju, uključujući njezine pristupne tokene i tokene za osvježavanje. Ponovno se povežite iz aplikacije ako je želite ponovno ovlastiti.

Otkrivanje za MCP klijente

Upotrijebite URL poslužitelja https://api.thunderphone.com/v1/mcp. Zahtjev bez valjane autentifikacije prima 401 uz:

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

Dohvatite taj dokument, a zatim dohvatite metapodatke autorizacijskog poslužitelja na https://api.thunderphone.com/.well-known/oauth-authorization-server. Metapodaci resursa dostupni su i na /.well-known/oauth-protected-resource/v1/mcp. Upotrijebite vraćene krajnje točke umjesto da ih sastavljate. Identifikator resursa jest https://api.thunderphone.com/v1/mcp.

Poslužitelj podržava autorizacijski kôd sa S256 PKCE, rotirajuće tokene za osvježavanje, javnu dinamičku registraciju klijenta, opoziv i dodjelu autorizacije uređaja. Ne postoje tajne klijenta ni implicitne dodjele. OpenID otkrivanje također je dostupno na /.well-known/openid-configuration; uključuje ista polja autorizacijskog poslužitelja te subject_types_supported: ["public"] i krajnju točku userinfo. ID tokeni i dokumenti metapodataka ID-a klijenta (CIMD) nisu podržani.

Registrirajte javnog klijenta

Pošaljite 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"]
}

Spremite vraćeni client_id. Preusmjeravanja moraju upotrebljavati HTTPS ili HTTP na 127.0.0.1 ili localhost. Registrirajte točan URI povratnog poziva, uključujući njegov priključak i putanju. Fragmenti i ugrađene vjerodajnice odbijaju se. Neobavezni client_uri i logo_uri moraju upotrebljavati HTTPS; ThunderPhone ih ne dohvaća tijekom registracije. Registracija je ograničena stopom zahtjeva. Registrirani klijenti ne istječu i ostaju registrirani kada se veza opozove. HTTPS povratni pozivi uključuju https://chatgpt.com/connector/oauth/<id> i https://chatgpt.com/connector_platform_oauth_redirect. Svaka veza može registrirati vlastitog klijenta.

Autorizacijski kôd

Otvorite otkrivenu krajnju točku za autorizaciju s parametrima client_id, točnim registriranim redirect_uri, response_type=code, nasumičnim state, scope, code_challenge, code_challenge_method=S256 i resource=https://api.thunderphone.com/v1/mcp. Izračunajte izazov kao base64url SHA-256 sažetak bez dopune svježeg PKCE provjeravatelja visoke entropije. Provjerite vraćene state i iss prije razmjene koda. Svaki odgovor na autorizaciju, uključujući odbijanje i pogreške protokola, identificira izdavatelja pomoću iss, koji točno odgovara otkrivenom issuer. Pogreške za nevaljanog klijenta ili povratni poziv vraćaju se lokalno bez preusmjeravanja na taj povratni poziv.

Izmijenite na POST /v1/oauth/token upotrebom kodiranja obrasca (prihvaća se i 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

Neobavezni parametar resource prihvaća se u zahtjevima za autorizaciju i token (uključujući razmjene za osvježavanje i uređaj). Kada je izostavljen, zadano je otkriveni MCP resurs. Kada je prisutan, mora točno odgovarati tom resursu; druge vrijednosti vraćaju invalid_target. Pristupni tokeni sadrže tu publiku, a MCP odbija tokene s nedostajućom ili drukčijom publikom s 401 i izazovom za otkrivanje.

Zahtjevi za autorizaciju i kodovi istječu nakon 10 minuta. Svaki odgovor s tokenom sadržava access_token, token_type (Bearer), expires_in (zadano 3600 sekundi), refresh_token, scope, organization_id i organization_name. Pristupne tokene šaljite samo putem zaglavlja Authorization: Bearer. Nikada ne stavljajte tokene u URL-ove, zapisnike, kontrolu izvornog koda ni chat.

Osvježite i opozovite

Osvježite s parametrima grant_type=refresh_token, client_id, refresh_token i resource na krajnjoj točki za token. Novi token za osvježavanje spremite atomski i prestanite upotrebljavati stari. Tokeni za osvježavanje istječu nakon 30 dana bez uspješnog osvježavanja. Neobavezni scope može suziti dodijeljena dopuštenja. offline_access uvijek je uključen i tokeni za osvježavanje uvijek se izdaju. Početni zahtjev bez scope dodjeljuje samo offline_access, stoga klijenti trebaju zatražiti dopuštenja koja trebaju.

Ponovna upotreba koda i ponovna upotreba rotiranog tokena za osvježavanje opozivaju cijelu autorizaciju. Serijalizirajte osvježavanja unutar klijenta; ponavljanje uspješno razmijenjene vjerodajnice nije sigurna strategija ponovnog pokušaja.

Za prekid veze pošaljite token i client_id na POST /v1/oauth/revoke. Opozivanje bilo kojeg tokena opoziva njegovu autorizaciju, uključujući sve tokene izdane iz njega. Nepoznati token vraća uspjeh bez otkrivanja postoji li. Sesije nadzorne ploče mogu navesti vlastite autorizacije na GET /v1/oauth/grants i opozvati jednu na DELETE /v1/oauth/grants/<id>, pri čemu X-ThunderPhone-Org odabire organizaciju.

Autorizacija uređaja

Autorizacija uređaja ograničena je na unaprijed registrirane klijente; dinamički registrirani klijenti primaju unauthorized_client. Unaprijed registrirani javni klijent thunderphone-cli podržava autorizaciju uređaja i osvježavanje. Pošaljite client_id=thunderphone-cli i scope na POST /v1/oauth/device/code. Korisniku prikažite user_code i verification_uri ili otvorite verification_uri_complete.

Ispitujte krajnju točku za token s parametrima grant_type=urn:ietf:params:oauth:grant-type:device_code, client_id i device_code, čekajući najmanje vraćeni interval (5 sekundi). Nastavite pri authorization_pending. Pri slow_down za svaki sljedeći zahtjev upotrijebite novi interval vraćen u odgovoru (povećan za 5 sekundi). Zaustavite se pri access_denied, expired_token ili bilo kojoj drugoj pogrešci. Nikada automatski ne odobravajte kôd uređaja.

Unaprijed registrirani klijent thunderphone-mcp prihvaća http://127.0.0.1/callback i http://localhost/callback na bilo kojem priključku. Shema, host, putanja i upit moraju odgovarati; razmjena tokena mora upotrebljavati točan URI preusmjeravanja (uključujući priključak) iz autorizacije. Dinamički registrirani klijenti zahtijevaju točno podudaranje URI-ja preusmjeravanja, uključujući priključak. Dinamički registrirajte drukčiji povratni poziv ako vam je potrebna druga putanja.

Provjere identiteta računa i domene radnog prostora

Zatražite oba opsega openid email uz opsege operacija koje vaš klijent treba. Pozovite otkrivenu userinfo_endpoint (GET /v1/oauth/userinfo) s pristupnim tokenom u zaglavlju Bearer. Uspješan odgovor sadržava:

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

sub je stabilni identifikator korisnika; org_id je organizacija odabrana tijekom pristanka. Krajnja točka zahtijeva oba opsega identiteta i vraća 403 ako bilo koji nedostaje. Vraća 403 s error=access_denied ako račun nema profil s potvrđenom e-poštom, umjesto da tvrdi da je nepotvrđena e-pošta pouzdana. Nevaljani, istekli, opozvani tokeni ili tokeni s pogrešnom publikom vraćaju 401. Tokeni sesije korisnika i API ključevi organizacije ne mogu pozvati userinfo. ID token se ne izdaje.

Dostupne dozvole

Obitelj	Opsezi
Agenti i uvoz agenata	`agents:read`, `agents:write`
Pozivi	`calls:read`, `calls:write`
Telefonski brojevi i VoIP	`numbers:read`, `numbers:write`
Znanje	`knowledge:read`, `knowledge:write`
Kampanje	`campaigns:read`, `campaigns:write`
Integracije, krajnje točke webhooka, MCP poslužitelji	`integrations:read`, `integrations:write`
Glasovi	`voices:read`
Testni scenariji, pokretanja testova, provjera valjanosti	`testing:read`, `testing:write`
Naplata	`billing:read`
Identitet računa i potvrđena e-pošta	`openid`, `email` (oba su potrebna za userinfo)
Trajna veza	`offline_access` (uvijek uključen)

GET, HEAD i OPTIONS koriste opsege za čitanje; druge metode koriste opsege za pisanje. Izmjene glasova i naplate nisu dostupne putem OAutha; POST /v1/voices/preview koristi voices:read jer pregledava glas bez promjene njegove konfiguracije. MCP alati primjenjuju opseg svoje temeljne REST operacije. Prijenosi između organizacija odbijaju se čak i kada korisnik koji autorizira pripada objema organizacijama. Ostale API obitelji, uključujući upravljanje API ključevima i postavke korisničkih računa, nisu dostupne putem OAutha. Nedostajuća dozvola za REST operaciju vraća 403 s WWW-Authenticate: Bearer error="insufficient_scope", scope="...". Nevažeći ili istekli pristupni tokeni vraćaju 401.

Signali autentikacije MCP alata

Svaki alat u tools/list uključuje securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}], s opsegom REST operacije tog alata. Alati za javnu dokumentaciju koriste prazan popis opsega i i dalje zahtijevaju autentificiranu vezu.

Valjani token kojem nedostaje opseg alata prima HTTP 200 s JSON-RPC result koji sadrži isError: true, objašnjavajući tekst u content i _meta["mcp/www_authenticate"]. Potonji je polje koje sadrži Bearer izazov s resource_metadata, error="insufficient_scope", error_description i potrebnim scope. Alat se ne izvršava. Upotrijebite ovaj izazov za zahtjev proširene privole. Nedostajuća ili nevažeća autentikacija i dalje vraća HTTP 401 s WWW-Authenticate; pogreške REST opsega i dalje vraćaju HTTP 403.

Zadržavanje vjerodajnica

API pokreće python manage.py oauth_cleanup svakog sata u staging i produkcijskom okruženju. Uklanja istekle zahtjeve za autorizaciju i kodove uređaja. Istekli pristupni tokeni, autorizacijski kodovi i sažeci refresh tokena uklanjaju se tek nakon što se njihovo odobrenje opozove ili cijela obitelj više nije aktivna. Iskorišteni sažeci zadržavaju se dok obitelj ima upotrebljiv refresh token, autorizacijski kod, odobreni kod uređaja ili pristupni token, kako čišćenje ne bi moglo onemogućiti otkrivanje ponovne upotrebe.