---
title: "Unganisha kwa OAuth"
description: "Idhinisha wateja wa MCP na CLI ya ThunderPhone bila kushiriki ufunguo wa API."
---

OAuth huruhusu programu kuunganishwa na shirika moja la ThunderPhone kwa ruhusa unazoidhinisha. Wateja wa saraka wanapaswa kutumia OAuth kwa chaguomsingi. Funguo za API za shirika zinaendelea kupatikana kwa wateja wanaohitaji tokeni ya Bearer iliyosanidiwa mwenyewe.

## Idhinisha muunganisho

Anzisha muunganisho katika mteja wako wa MCP. Ingia kwenye ThunderPhone, angalia jina la programu na ruhusa zilizoombwa, chagua shirika, kisha uchague **Idhinisha**. Chagua **Kataa** ikiwa hukuanzisha muunganisho au huiamini programu. Majina ya programu hutolewa na wasanidi wake na si uthibitisho wa uaminifu.

Ruhusa za kusoma hutoa ufikiaji wa data iliyotajwa, ikijumuisha rekodi na nakala za mazungumzo wakati `calls:read` inapoombwa. Ruhusa za kuandika zinaweza kubadilisha au kufuta rasilimali; simu, kampeni, ununuzi wa namba za simu, na utumaji zinaweza kusababisha gharama au kuathiri mazingira ya uzalishaji. Jukumu lako katika shirika bado linatumika.

Kwa muunganisho wa CLI, fungua kiungo cha uthibitishaji kinachoonyeshwa kwenye terminal yako, linganisha msimbo wa herufi nane, chagua shirika lako, kisha idhinisha. Kufungua kiungo pekee hakutoi ufikiaji. Misimbo inaisha muda baada ya dakika 15.

## Ondoa muunganisho wa programu

Fungua **Shirika → Funguo za API → Programu zilizoidhinishwa** katika dashibodi na uchague **Batilisha**. Hii inabatilisha idhini uliyochagua kwa shirika la sasa, ikijumuisha tokeni zake za ufikiaji na za kuhuisha. Unganisha tena kutoka kwenye programu ikiwa unataka kuiidhinisha tena.

## Ugunduzi kwa wateja wa MCP

Tumia URL ya seva `https://api.thunderphone.com/v1/mcp`. Ombi lisilo na uthibitishaji halali hupokea `401` yenye:

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

Chukua hati hiyo, kisha chukua metadata ya seva ya uidhinishaji kwenye `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Metadata ya rasilimali pia inapatikana kwenye `/.well-known/oauth-protected-resource/v1/mcp`. Tumia vituo vilivyorejeshwa badala ya kuviunda. Kitambulisho cha rasilimali ni `https://api.thunderphone.com/v1/mcp`.

Seva inasaidia msimbo wa uidhinishaji wenye **S256 PKCE**, tokeni za uonyeshaji upya zinazozungushwa, usajili wa umma unaobadilika wa mteja, ubatilishaji, na ruzuku ya uidhinishaji wa kifaa. Hakuna siri za mteja au ruzuku dhahania. Ugunduzi wa OpenID pia unapatikana kwenye `/.well-known/openid-configuration`; unajumuisha sehemu zilezile za seva ya uidhinishaji pamoja na `subject_types_supported: ["public"]` na kituo cha userinfo. Tokeni za ID na Nyaraka za Metadata za Kitambulisho cha Mteja (CIMD) hazisaidiki.

### Sajili mteja wa umma

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

Hifadhi `client_id` iliyorejeshwa. Uelekezaji upya lazima utumie HTTPS, au HTTP kwenye `127.0.0.1` au `localhost`. Sajili URI sahihi ya mwito-rejea, ikijumuisha mlango na njia yake. Vipande na vitambulisho vilivyopachikwa vinakataliwa. `client_uri` na `logo_uri` za hiari lazima zitumie HTTPS; ThunderPhone haichukui hizo wakati wa usajili. Usajili una kikomo cha kiwango cha maombi. Wateja waliosajiliwa hawaishi muda wake na husalia wamesajiliwa muunganisho unapobatilishwa. Mito-rejea ya HTTPS inajumuisha `https://chatgpt.com/connector/oauth/<id>` na `https://chatgpt.com/connector_platform_oauth_redirect`. Kila muunganisho unaweza kusajili mteja wake mwenyewe.

### Msimbo wa uidhinishaji

Fungua kituo cha uidhinishaji kilichogunduliwa kwa `client_id`, `redirect_uri` sahihi iliyosajiliwa, `response_type=code`, `state` ya nasibu, `scope`, `code_challenge`, `code_challenge_method=S256`, na `resource=https://api.thunderphone.com/v1/mcp`. Hesabu changamoto kama muhtasari wa SHA-256 wa base64url usiojazwa wa kithibitishaji kipya cha PKCE chenye entropia ya juu. Thibitisha `state` na `iss` zilizorejeshwa kabla ya kubadilisha msimbo. Kila jibu la uidhinishaji, ikijumuisha kunyimwa na hitilafu za itifaki, humtambua mtoaji kwa `iss`, inayolingana kabisa na `issuer` iliyogunduliwa. Hitilafu za mteja au mwito-rejea usio halali hurejeshwa moja kwa moja bila kuelekeza upya kwenye mwito-rejea huo.

Badilisha kwenye `POST /v1/oauth/token` ukitumia usimbaji wa fomu (JSON pia inakubaliwa):

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

Kigezo cha hiari cha `resource` kinakubaliwa kwenye maombi yote ya uidhinishaji na tokeni (ikijumuisha ubadilishanaji wa uonyeshaji upya na kifaa). Kisipotolewa, hutumia rasilimali ya MCP iliyogunduliwa kama chaguo-msingi. Kikikuwepo, lazima kilingane kabisa na rasilimali hiyo; thamani nyingine hurejesha `invalid_target`. Tokeni za ufikiaji hubeba walengwa hao, na MCP hukataa tokeni zisizo na walengwa au zenye walengwa tofauti kwa `401` na changamoto ya ugunduzi.

Maombi ya uidhinishaji na misimbo huisha baada ya dakika 10. Kila jibu la tokeni lina `access_token`, `token_type` (`Bearer`), `expires_in` (sekunde 3600 kwa chaguo-msingi), `refresh_token`, `scope`, `organization_id`, na `organization_name`. Tuma tokeni za ufikiaji kupitia kichwa cha `Authorization: Bearer` pekee. Usiweke tokeni kamwe kwenye URL, kumbukumbu, udhibiti wa toleo la chanzo, au mazungumzo.

### Onyesha upya na batilisha

Onyesha upya kwa `grant_type=refresh_token`, `client_id`, `refresh_token`, na `resource` kwenye kituo cha tokeni. Hifadhi tokeni mpya ya uonyeshaji upya kwa utaratibu wa atomiki na acha kutumia ya zamani. Tokeni za uonyeshaji upya huisha baada ya siku 30 bila uonyeshaji upya uliofanikiwa. `scope` ya hiari inaweza kupunguza ruhusa zilizotolewa. `offline_access` hujumuishwa kila wakati na tokeni za uonyeshaji upya hutolewa kila wakati. Ombi la awali lisilo na `scope` hutoa `offline_access` pekee, kwa hivyo wateja wanapaswa kuomba ruhusa wanazohitaji.

Kutumia tena msimbo na kutumia tena tokeni ya uonyeshaji upya iliyozungushwa hubatilisha uidhinishaji wote. Tekeleza uonyeshaji upya mmoja baada ya mwingine ndani ya mteja; kurudia kutuma kitambulisho kilichobadilishwa kwa mafanikio si mkakati salama wa kujaribu tena.

Ili kukata muunganisho, tuma `token` na `client_id` kwa `POST /v1/oauth/revoke`. Kubatilisha tokeni yoyote hubatilisha uidhinishaji wake, ikijumuisha tokeni zote zilizotolewa kutokana nayo. Tokeni isiyojulikana hurejesha mafanikio bila kufichua kama ipo. Vipindi vya dashibodi vinaweza kuorodhesha uidhinishaji wake kwenye `GET /v1/oauth/grants` na kubatilisha mmoja kwenye `DELETE /v1/oauth/grants/<id>`, huku `X-ThunderPhone-Org` ikichagua shirika.

### Uidhinishaji wa kifaa

Uidhinishaji wa kifaa unaruhusiwa kwa wateja waliosajiliwa mapema pekee; wateja waliosajiliwa kwa njia inayobadilika hupokea `unauthorized_client`. Mteja wa umma aliyesajiliwa mapema `thunderphone-cli` anasaidia uidhinishaji wa kifaa na uonyeshaji upya. Tuma `client_id=thunderphone-cli` na `scope` kwa `POST /v1/oauth/device/code`. Mwonyeshe mtumiaji `user_code` na `verification_uri`, au fungua `verification_uri_complete`.

Hoji kituo cha tokeni mara kwa mara kwa `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id`, na `device_code`, ukisubiri angalau `interval` iliyorejeshwa (sekunde 5). Endelea unapopokea `authorization_pending`. Kwenye `slow_down`, tumia `interval` mpya iliyorejeshwa kwenye jibu (iliyoongezwa kwa sekunde 5) kwa kila ombi linalofuata. Simama kwenye `access_denied`, `expired_token`, au hitilafu nyingine yoyote. Usiidhinishe kamwe msimbo wa kifaa kiotomatiki.

Mteja aliyesajiliwa mapema `thunderphone-mcp` anakubali `http://127.0.0.1/callback` na `http://localhost/callback` kwenye mlango wowote. Itifaki, seva pangishi, njia na kigezo cha utafutaji lazima vilingane; ubadilishanaji wa tokeni lazima utumie URI sahihi ya uelekezaji upya (ikijumuisha mlango) kutoka kwenye uidhinishaji. Wateja waliosajiliwa kwa njia inayobadilika wanahitaji ulinganishaji sahihi wa URI ya uelekezaji upya, ikijumuisha mlango. Sajili mwito-rejea tofauti kwa njia inayobadilika ikiwa unahitaji njia nyingine.

### Utambulisho wa akaunti na ukaguzi wa kikoa cha nafasi ya kazi

Omba `openid email` pamoja na vigo vya ruhusa za operesheni ambavyo mteja wako anahitaji. Piga `userinfo_endpoint` iliyogunduliwa (`GET /v1/oauth/userinfo`) kwa tokeni ya ufikiaji kwenye kichwa cha Bearer. Jibu lililofanikiwa lina:

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

`sub` ni kitambulisho thabiti cha mtumiaji; `org_id` ni shirika lililochaguliwa wakati wa idhini. Kituo hiki kinahitaji vigo vyote viwili vya utambulisho na hurejesha `403` iwapo kimoja kinakosekana. Hurejesha `403` yenye `error=access_denied` ikiwa akaunti haina wasifu wa barua pepe uliothibitishwa, badala ya kudai kuwa barua pepe isiyothibitishwa inaaminika. Tokeni zisizo halali, zilizoisha muda wake, zilizobatilishwa, au zenye walengwa wasio sahihi hurejesha `401`. Tokeni za vipindi vya watumiaji na funguo za API za shirika haziwezi kupiga userinfo. Hakuna tokeni ya ID inayotolewa.

## Ruhusa zinazopatikana

| Kundi | Scope |
| --- | --- |
| Ejenti na uagizaji wa ejenti | `agents:read`, `agents:write` |
| Simu | `calls:read`, `calls:write` |
| Nambari za simu na VoIP | `numbers:read`, `numbers:write` |
| Maarifa | `knowledge:read`, `knowledge:write` |
| Kampeni | `campaigns:read`, `campaigns:write` |
| Miunganisho, vituo vya mwisho vya webhook, seva za MCP | `integrations:read`, `integrations:write` |
| Sauti | `voices:read` |
| Matukio ya majaribio, utekelezaji wa majaribio, uthibitishaji | `testing:read`, `testing:write` |
| Malipo | `billing:read` |
| Utambulisho wa akaunti na barua pepe iliyothibitishwa | `openid`, `email` (zote zinahitajika kwa userinfo) |
| Muunganisho endelevu | `offline_access` (hujumuishwa kila wakati) |

GET, HEAD na OPTIONS hutumia scope za kusoma; mbinu nyingine hutumia scope za kuandika. Mabadiliko ya sauti na malipo hayapatikani kupitia OAuth; `POST /v1/voices/preview` hutumia `voices:read` kwa sababu huhakiki sauti bila kubadilisha usanidi wake. Zana za MCP zinatekeleza scope ya operesheni yao ya msingi ya REST. Uhamishaji kati ya mashirika hukataliwa hata wakati mtumiaji anayeidhinisha ni mwanachama wa mashirika yote mawili. Familia nyingine za API, ikiwemo usimamizi wa API key na mipangilio ya akaunti za watumiaji, hazipatikani kupitia OAuth. Ruhusa inayokosekana kwenye operesheni ya REST hurejesha `403` pamoja na `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Tokeni za ufikiaji zisizo halali au zilizoisha muda wake hurejesha `401`.


### Ishara za uthibitishaji wa zana za MCP

Kila zana katika `tools/list` inajumuisha `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]`, pamoja na scope ya operesheni ya REST ya zana hiyo. Zana za nyaraka za umma hutumia orodha tupu ya scope na bado zinahitaji muunganisho uliothibitishwa.

Tokeni halali inayokosa scope ya zana hupokea HTTP `200` pamoja na `result` ya JSON-RPC iliyo na `isError: true`, maelezo katika `content`, na `_meta["mcp/www_authenticate"]`. Kipengele cha mwisho ni mkusanyiko unaojumuisha changamoto ya Bearer yenye `resource_metadata`, `error="insufficient_scope"`, `error_description`, na `scope` inayohitajika. Zana haitekelezwi. Tumia changamoto hii kuomba idhini iliyopanuliwa. Uthibitishaji unaokosekana au usio halali unaendelea kurejesha HTTP `401` pamoja na `WWW-Authenticate`; hitilafu za scope za REST zinaendelea kurejesha HTTP `403`.

## Uhifadhi wa vitambulisho

API huendesha `python manage.py oauth_cleanup` kila saa katika staging na production. Huondoa maombi ya uidhinishaji na misimbo ya kifaa iliyoisha muda wake. Tokeni za ufikiaji zilizoisha muda wake, misimbo ya uidhinishaji na hash za refresh token hupunguzwa tu baada ya idhini yake kufutwa au familia nzima kutotumika tena. Hash zilizotumika huhifadhiwa wakati familia ina refresh token, msimbo wa uidhinishaji, msimbo wa kifaa ulioidhinishwa au tokeni ya ufikiaji inayoweza kutumika, hivyo usafishaji hauwezi kuzima utambuzi wa matumizi ya kurudia.