---
title: "Povežite se z OAuth"
description: "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:

```http
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`:

```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"]
}
```

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):

```text
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:

```json
{
  "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.