---
title: "OAuthతో కనెక్ట్ అవ్వండి"
description: "API కీని పంచుకోకుండా MCP క్లయింట్లు మరియు ThunderPhone CLIకి అధికారం ఇవ్వండి."
---

OAuth మీరు ఆమోదించే అనుమతులతో ఒక యాప్‌ను ఒకే ThunderPhone సంస్థకు కనెక్ట్ చేయడానికి అనుమతిస్తుంది. డైరెక్టరీ క్లయింట్లు డిఫాల్ట్‌గా OAuthను ఉపయోగించాలి. మాన్యువల్‌గా కాన్ఫిగర్ చేసిన Bearer టోకెన్ అవసరమైన క్లయింట్ల కోసం సంస్థ API కీలు అందుబాటులోనే ఉంటాయి.

## కనెక్షన్‌ను ఆమోదించండి

మీ MCP క్లయింట్‌లో కనెక్షన్‌ను ప్రారంభించండి. ThunderPhoneకు సైన్ ఇన్ చేసి, యాప్ పేరు మరియు అభ్యర్థించిన అనుమతులను పరిశీలించి, ఒక సంస్థను ఎంచుకుని, **ఆమోదించండి** ఎంచుకోండి. మీరు కనెక్షన్‌ను ప్రారంభించకపోయినా లేదా యాప్‌ను విశ్వసించకపోయినా **తిరస్కరించండి** ఎంచుకోండి. యాప్ పేర్లను వాటి డెవలపర్‌లు అందిస్తారు; అవి ధృవీకరణ బ్యాడ్జ్ కాదు.

రీడ్ అనుమతులు పేర్కొన్న డేటాకు ప్రాప్యతను అందిస్తాయి, `calls:read` అభ్యర్థించినప్పుడు రికార్డింగ్‌లు మరియు ట్రాన్స్‌క్రిప్ట్‌లు కూడా ఇందులో ఉంటాయి. రైట్ అనుమతులు వనరులను మార్చవచ్చు లేదా తొలగించవచ్చు; కాల్‌లు, క్యాంపెయిన్‌లు, ఫోన్ కొనుగోళ్లు, మరియు డిప్లాయ్‌మెంట్‌లు ఖర్చులను కలిగించవచ్చు లేదా ప్రొడక్షన్‌పై ప్రభావం చూపవచ్చు. మీ సంస్థ పాత్ర వర్తిస్తూనే ఉంటుంది.

CLI కనెక్షన్ కోసం, మీ టెర్మినల్‌లో చూపిన ధృవీకరణ లింక్‌ను తెరిచి, ఎనిమిది-అక్షరాల కోడ్‌ను సరిపోల్చి, మీ సంస్థను ఎంచుకుని, ఆమోదించండి. లింక్‌ను తెరవడం మాత్రమే ప్రాప్యతను మంజూరు చేయదు. కోడ్‌ల గడువు 15 నిమిషాల తర్వాత ముగుస్తుంది.

## యాప్‌ను డిస్‌కనెక్ట్ చేయండి

డ్యాష్‌బోర్డ్‌లో **సంస్థ → API కీలు → అధీకృత యాప్‌లు** తెరిచి, **ఉపసంహరించండి** ఎంచుకోండి. ఇది ప్రస్తుత సంస్థ కోసం మీరు ఎంచుకున్న అధీకరణను, దాని యాక్సెస్ మరియు రిఫ్రెష్ టోకెన్‌లతో సహా, ఉపసంహరిస్తుంది. యాప్‌కు మళ్లీ అధీకరణ ఇవ్వాలనుకుంటే దాని నుంచి మళ్లీ కనెక్ట్ చేయండి.

## MCP క్లయింట్‌ల కోసం డిస్కవరీ

సర్వర్ URL `https://api.thunderphone.com/v1/mcp` ఉపయోగించండి. చెల్లుబాటు అయ్యే ప్రమాణీకరణ లేని అభ్యర్థనకు `401` వస్తుంది, దీనితో:

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

ఆ డాక్యుమెంట్‌ను పొందండి, తర్వాత `https://api.thunderphone.com/.well-known/oauth-authorization-server` వద్ద ఆథరైజేషన్ సర్వర్ మెటాడేటాను పొందండి. రిసోర్స్ మెటాడేటా `/.well-known/oauth-protected-resource/v1/mcp` వద్ద కూడా అందుబాటులో ఉంటుంది. ఎండ్‌పాయింట్‌లను నిర్మించకుండా, తిరిగి వచ్చిన ఎండ్‌పాయింట్‌లను ఉపయోగించండి. రిసోర్స్ ఐడెంటిఫైయర్ `https://api.thunderphone.com/v1/mcp`.

సర్వర్ **S256 PKCE**తో ఆథరైజేషన్ కోడ్, రొటేట్ అయ్యే రిఫ్రెష్ టోకెన్‌లు, పబ్లిక్ డైనమిక్ క్లయింట్ రిజిస్ట్రేషన్, రివొకేషన్, మరియు డివైస్ ఆథరైజేషన్ గ్రాంట్‌కు మద్దతు ఇస్తుంది. క్లయింట్ సీక్రెట్‌లు లేదా ఇంప్లిసిట్ గ్రాంట్‌లు లేవు. OpenID డిస్కవరీ కూడా `/.well-known/openid-configuration` వద్ద అందుబాటులో ఉంది; ఇందులో అదే ఆథరైజేషన్-సర్వర్ ఫీల్డ్‌లు, అలాగే `subject_types_supported: ["public"]` మరియు యూజర్‌ఇన్ఫో ఎండ్‌పాయింట్ ఉంటాయి. ID టోకెన్‌లు మరియు క్లయింట్ ID మెటాడేటా డాక్యుమెంట్‌లు (CIMD)కు మద్దతు లేదు.

### పబ్లిక్ క్లయింట్‌ను రిజిస్టర్ చేయండి

`POST /v1/oauth/register`కు JSON పంపండి:

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

తిరిగి వచ్చిన `client_id`ను సేవ్ చేయండి. రీడైరెక్ట్‌లు తప్పనిసరిగా HTTPSను, లేదా `127.0.0.1` లేదా `localhost`పై HTTPను ఉపయోగించాలి. పోర్ట్ మరియు పాత్‌తో సహా ఖచ్చితమైన కాల్‌బ్యాక్ URIను రిజిస్టర్ చేయండి. ఫ్రాగ్మెంట్‌లు మరియు ఎంబెడెడ్ క్రెడెన్షియల్‌లు తిరస్కరించబడతాయి. ఐచ్ఛిక `client_uri` మరియు `logo_uri` తప్పనిసరిగా HTTPSను ఉపయోగించాలి; రిజిస్ట్రేషన్ సమయంలో ThunderPhone వాటిని పొందదు. రిజిస్ట్రేషన్‌కు రేట్ పరిమితి ఉంటుంది. రిజిస్టర్ చేసిన క్లయింట్‌ల గడువు ముగియదు మరియు కనెక్షన్ రద్దు చేసినప్పుడు కూడా అవి రిజిస్టర్ అయి ఉంటాయి. HTTPS కాల్‌బ్యాక్‌లలో `https://chatgpt.com/connector/oauth/<id>` మరియు `https://chatgpt.com/connector_platform_oauth_redirect` ఉంటాయి. ప్రతి కనెక్షన్ తన స్వంత క్లయింట్‌ను రిజిస్టర్ చేయవచ్చు.

### ఆథరైజేషన్ కోడ్

కనుగొన్న ఆథరైజేషన్ ఎండ్‌పాయింట్‌ను `client_id`, ఖచ్చితంగా రిజిస్టర్ చేసిన `redirect_uri`, `response_type=code`, యాదృచ్ఛిక `state`, `scope`, `code_challenge`, `code_challenge_method=S256`, మరియు `resource=https://api.thunderphone.com/v1/mcp`తో తెరవండి. తాజా అధిక-ఎంట్రోపీ PKCE వెరిఫైయర్ యొక్క ప్యాడింగ్ లేని base64url SHA-256 డైజెస్ట్‌గా ఛాలెంజ్‌ను గణించండి. కోడ్‌ను ఎక్స్చేంజ్ చేయడానికి ముందు తిరిగి వచ్చిన `state` మరియు `iss`ను తనిఖీ చేయండి. తిరస్కరణ మరియు ప్రోటోకాల్ లోపాలతో సహా ప్రతి ఆథరైజేషన్ ప్రతిస్పందన, కనుగొన్న `issuer`తో ఖచ్చితంగా సరిపోలే `iss`తో ఇష్యూయర్‌ను గుర్తిస్తుంది. చెల్లని క్లయింట్ లేదా కాల్‌బ్యాక్‌కు సంబంధించిన లోపాలు ఆ కాల్‌బ్యాక్‌కు రీడైరెక్ట్ చేయకుండా స్థానికంగా తిరిగి వస్తాయి.

ఫారమ్ ఎన్‌కోడింగ్ ఉపయోగించి `POST /v1/oauth/token` వద్ద ఎక్స్చేంజ్ చేయండి (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
```

ఐచ్ఛిక `resource` పారామీటర్ ఆథరైజేషన్ మరియు టోకెన్ అభ్యర్థనలు రెండింటిలోనూ ఆమోదించబడుతుంది (రిఫ్రెష్ మరియు డివైస్ ఎక్స్చేంజ్‌లతో సహా). ఇవ్వనప్పుడు, ఇది కనుగొన్న MCP రిసోర్స్‌కు డిఫాల్ట్ అవుతుంది. ఉన్నప్పుడు, ఇది ఆ రిసోర్స్‌తో ఖచ్చితంగా సరిపోలాలి; ఇతర విలువలు `invalid_target`ను తిరిగి ఇస్తాయి. యాక్సెస్ టోకెన్‌లు ఆ ఆడియన్స్‌ను కలిగి ఉంటాయి, మరియు ఆడియన్స్ లేని లేదా భిన్నమైన ఆడియన్స్ ఉన్న టోకెన్‌లను MCP `401` మరియు డిస్కవరీ ఛాలెంజ్‌తో తిరస్కరిస్తుంది.

ఆథరైజేషన్ అభ్యర్థనలు మరియు కోడ్‌ల గడువు 10 నిమిషాల తర్వాత ముగుస్తుంది. ప్రతి టోకెన్ ప్రతిస్పందనలో `access_token`, `token_type` (`Bearer`), `expires_in` (డిఫాల్ట్‌గా 3600 సెకన్లు), `refresh_token`, `scope`, `organization_id`, మరియు `organization_name` ఉంటాయి. యాక్సెస్ టోకెన్‌లను `Authorization: Bearer` హెడర్ ద్వారానే పంపండి. టోకెన్‌లను ఎప్పుడూ URLలు, లాగ్‌లు, సోర్స్ కంట్రోల్ లేదా చాట్‌లో ఉంచవద్దు.

### రిఫ్రెష్ మరియు రద్దు

టోకెన్ ఎండ్‌పాయింట్ వద్ద `grant_type=refresh_token`, `client_id`, `refresh_token`, మరియు `resource`తో రిఫ్రెష్ చేయండి. కొత్త రిఫ్రెష్ టోకెన్‌ను అటామిక్‌గా సేవ్ చేసి, పాతదాన్ని ఉపయోగించడం ఆపండి. విజయవంతమైన రిఫ్రెష్ లేకుండా 30 రోజుల తర్వాత రిఫ్రెష్ టోకెన్‌ల గడువు ముగుస్తుంది. ఐచ్ఛిక `scope` మంజూరు చేసిన అనుమతులను పరిమితం చేయవచ్చు. `offline_access` ఎల్లప్పుడూ చేర్చబడుతుంది మరియు రిఫ్రెష్ టోకెన్‌లు ఎల్లప్పుడూ జారీ అవుతాయి. `scope` లేని ప్రారంభ అభ్యర్థన కేవలం `offline_access`ను మాత్రమే మంజూరు చేస్తుంది, కాబట్టి క్లయింట్‌లు తమకు అవసరమైన అనుమతులను అభ్యర్థించాలి.

కోడ్ పునర్వినియోగం మరియు రొటేట్ చేసిన రిఫ్రెష్-టోకెన్ పునర్వినియోగం మొత్తం ఆథరైజేషన్‌ను రద్దు చేస్తాయి. క్లయింట్‌లో రిఫ్రెష్‌లను వరుసగా నిర్వహించండి; విజయవంతంగా ఎక్స్చేంజ్ చేసిన క్రెడెన్షియల్‌ను మళ్లీ పంపడం సురక్షితమైన రీట్రై వ్యూహం కాదు.

డిస్‌కనెక్ట్ చేయడానికి, `POST /v1/oauth/revoke`కు `token` మరియు `client_id` పంపండి. ఏ టోకెన్‌ను రద్దు చేసినా, దాని నుండి జారీ చేసిన అన్ని టోకెన్‌లతో సహా దాని ఆథరైజేషన్ రద్దు అవుతుంది. తెలియని టోకెన్ ఉనికిలో ఉందో లేదో వెల్లడించకుండా విజయాన్ని తిరిగి ఇస్తుంది. డ్యాష్‌బోర్డ్ సెషన్‌లు తమ స్వంత ఆథరైజేషన్‌లను `GET /v1/oauth/grants` వద్ద జాబితా చేయగలవు మరియు సంస్థను ఎంచుకోవడానికి `X-ThunderPhone-Org`ను ఉపయోగిస్తూ, ఒకదాన్ని `DELETE /v1/oauth/grants/<id>` వద్ద రద్దు చేయగలవు.

### డివైస్ ఆథరైజేషన్

డివైస్ ఆథరైజేషన్ ముందుగా రిజిస్టర్ చేసిన క్లయింట్‌లకు మాత్రమే పరిమితం చేయబడింది; డైనమిక్‌గా రిజిస్టర్ చేసిన క్లయింట్‌లకు `unauthorized_client` వస్తుంది. ముందుగా రిజిస్టర్ చేసిన పబ్లిక్ క్లయింట్ `thunderphone-cli` డివైస్ ఆథరైజేషన్ మరియు రిఫ్రెష్‌కు మద్దతు ఇస్తుంది. `POST /v1/oauth/device/code`కు `client_id=thunderphone-cli` మరియు `scope` పంపండి. యూజర్‌కు `user_code` మరియు `verification_uri`ను చూపండి లేదా `verification_uri_complete`ను తెరవండి.

కనీసం తిరిగి వచ్చిన `interval` (5 సెకన్లు) వేచి ఉండి, టోకెన్ ఎండ్‌పాయింట్‌ను `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id`, మరియు `device_code`తో పోల్ చేయండి. `authorization_pending`పై కొనసాగించండి. `slow_down`పై, ప్రతి తదుపరి అభ్యర్థనకు ప్రతిస్పందనలో తిరిగి వచ్చిన కొత్త `interval`ను (5 సెకన్లు పెంచబడినది) ఉపయోగించండి. `access_denied`, `expired_token`, లేదా ఏదైనా ఇతర లోపంపై ఆపండి. డివైస్ కోడ్‌ను ఎప్పుడూ స్వయంచాలకంగా ఆమోదించవద్దు.

ముందుగా రిజిస్టర్ చేసిన `thunderphone-mcp` క్లయింట్ ఏ పోర్ట్‌లోనైనా `http://127.0.0.1/callback` మరియు `http://localhost/callback`ను అంగీకరిస్తుంది. స్కీమ్, హోస్ట్, పాత్ మరియు క్వెరీ సరిపోలాలి; టోకెన్ ఎక్స్చేంజ్ తప్పనిసరిగా ఆథరైజేషన్ నుండి వచ్చిన ఖచ్చితమైన రీడైరెక్ట్ URIను (పోర్ట్‌తో సహా) ఉపయోగించాలి. డైనమిక్‌గా రిజిస్టర్ చేసిన క్లయింట్‌లకు పోర్ట్‌తో సహా ఖచ్చితమైన రీడైరెక్ట్-URI సరిపోలిక అవసరం. మీకు వేరొక పాత్ అవసరమైతే వేరే కాల్‌బ్యాక్‌ను డైనమిక్‌గా రిజిస్టర్ చేయండి.

### ఖాతా గుర్తింపు మరియు వర్క్‌స్పేస్ డొమైన్ తనిఖీలు

మీ క్లయింట్‌కు అవసరమైన ఆపరేషన్ స్కోప్‌లతో పాటు `openid email` రెండింటినీ అభ్యర్థించండి. Bearer హెడర్‌లో యాక్సెస్ టోకెన్‌తో కనుగొన్న `userinfo_endpoint`ను (`GET /v1/oauth/userinfo`) కాల్ చేయండి. విజయవంతమైన ప్రతిస్పందనలో ఇవి ఉంటాయి:

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

`sub` స్థిరమైన యూజర్ ఐడెంటిఫైయర్; `org_id` అనేది సమ్మతి సమయంలో ఎంచుకున్న సంస్థ. ఎండ్‌పాయింట్‌కు రెండు గుర్తింపు స్కోప్‌లు అవసరం మరియు ఏదైనా లేకపోతే `403`ను తిరిగి ఇస్తుంది. ధృవీకరించని ఇమెయిల్ విశ్వసనీయమని నిర్ధారించకుండా, ఖాతాకు ధృవీకరించిన ఇమెయిల్ ప్రొఫైల్ లేకపోతే `error=access_denied`తో `403`ను తిరిగి ఇస్తుంది. చెల్లని, గడువు ముగిసిన, రద్దు చేసిన లేదా తప్పు-ఆడియన్స్ టోకెన్‌లు `401`ను తిరిగి ఇస్తాయి. మానవ సెషన్ టోకెన్‌లు మరియు సంస్థ API కీలు యూజర్‌ఇన్ఫోను కాల్ చేయలేవు. ID టోకెన్ జారీ చేయబడదు.

## అందుబాటులో ఉన్న అనుమతులు

| విభాగం | స్కోప్‌లు |
| --- | --- |
| ఏజెంట్‌లు మరియు ఏజెంట్ దిగుమతులు | `agents:read`, `agents:write` |
| కాల్స్ | `calls:read`, `calls:write` |
| ఫోన్ నంబర్‌లు మరియు VoIP | `numbers:read`, `numbers:write` |
| పరిజ్ఞానం | `knowledge:read`, `knowledge:write` |
| క్యాంపెయిన్‌లు | `campaigns:read`, `campaigns:write` |
| ఇంటిగ్రేషన్‌లు, webhook ఎండ్‌పాయింట్‌లు, MCP సర్వర్‌లు | `integrations:read`, `integrations:write` |
| స్వరాలు | `voices:read` |
| పరీక్షా దృశ్యాలు, పరీక్షా రన్‌లు, ధ్రువీకరణ | `testing:read`, `testing:write` |
| బిల్లింగ్ | `billing:read` |
| ఖాతా గుర్తింపు మరియు ధ్రువీకరించిన ఇమెయిల్ | `openid`, `email` (userinfo కోసం రెండూ అవసరం) |
| నిరంతర కనెక్షన్ | `offline_access` (ఎల్లప్పుడూ చేర్చబడుతుంది) |

GET, HEAD మరియు OPTIONS రీడ్ స్కోప్‌లను ఉపయోగిస్తాయి; ఇతర పద్ధతులు రైట్ స్కోప్‌లను ఉపయోగిస్తాయి. OAuth ద్వారా స్వర మరియు బిల్లింగ్ మార్పులు అందుబాటులో ఉండవు; `POST /v1/voices/preview` స్వర కాన్ఫిగరేషన్‌ను మార్చకుండా దానిని ప్రివ్యూ చేస్తుంది కాబట్టి `voices:read`ను ఉపయోగిస్తుంది. MCP టూల్‌లు వాటి అంతర్లీన REST ఆపరేషన్ స్కోప్‌ను అమలు చేస్తాయి. అధీకరించే వినియోగదారు రెండు సంస్థలకు చెందినప్పటికీ, సంస్థల మధ్య బదిలీలు నిరాకరించబడతాయి. API-కీ నిర్వహణ మరియు మానవ ఖాతా సెట్టింగ్‌లతో సహా ఇతర API విభాగాలు OAuth ద్వారా అందుబాటులో ఉండవు. REST ఆపరేషన్‌లో అనుమతి లేకపోతే `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`తో `403` తిరిగి వస్తుంది. చెల్లని లేదా గడువు ముగిసిన యాక్సెస్ టోకెన్‌లు `401`ను తిరిగి ఇస్తాయి.


### MCP టూల్ ప్రామాణీకరణ సంకేతాలు

`tools/list`లోని ప్రతి టూల్, ఆ టూల్ REST ఆపరేషన్ స్కోప్‌తో పాటు `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]`ను కలిగి ఉంటుంది. పబ్లిక్ డాక్యుమెంటేషన్ టూల్‌లు ఖాళీ స్కోప్ జాబితాను ఉపయోగిస్తాయి మరియు ఇప్పటికీ ప్రామాణీకరించిన కనెక్షన్ అవసరం.

టూల్ స్కోప్ లేని చెల్లుబాటు అయ్యే టోకెన్‌కు, `isError: true`ను కలిగిన JSON-RPC `result`, `content`లో వివరణాత్మక వచనం, మరియు `_meta["mcp/www_authenticate"]`తో HTTP `200` అందుతుంది. చివరిది `resource_metadata`, `error="insufficient_scope"`, `error_description`, మరియు అవసరమైన `scope`తో Bearer ఛాలెంజ్‌ను కలిగిన అరే. టూల్ అమలు చేయబడదు. విస్తరించిన సమ్మతిని అభ్యర్థించడానికి ఈ ఛాలెంజ్‌ను ఉపయోగించండి. లేని లేదా చెల్లని ప్రామాణీకరణకు `WWW-Authenticate`తో HTTP `401` తిరిగి వస్తూనే ఉంటుంది; REST స్కోప్ వైఫల్యాలకు HTTP `403` తిరిగి వస్తూనే ఉంటుంది.

## క్రెడెన్షియల్ నిల్వ

API, స్టేజింగ్ మరియు ప్రొడక్షన్‌లో ప్రతి గంటకు `python manage.py oauth_cleanup`ను అమలు చేస్తుంది. ఇది గడువు ముగిసిన అధీకరణ అభ్యర్థనలు మరియు డివైస్ కోడ్‌లను తొలగిస్తుంది. గడువు ముగిసిన యాక్సెస్ టోకెన్‌లు, అధీకరణ కోడ్‌లు మరియు రిఫ్రెష్-టోకెన్ హ్యాష్‌లు వాటి గ్రాంట్ రద్దు చేయబడిన తర్వాత లేదా మొత్తం ఫ్యామిలీ నిష్క్రియమైన తర్వాత మాత్రమే తొలగించబడతాయి. ఫ్యామిలీకి ఉపయోగించదగిన రిఫ్రెష్ టోకెన్, అధీకరణ కోడ్, ఆమోదించబడిన డివైస్ కోడ్ లేదా యాక్సెస్ టోకెన్ ఉన్నంత వరకు ఉపయోగించిన హ్యాష్‌లు నిల్వ చేయబడతాయి, కాబట్టి క్లీనప్ రీప్లే గుర్తింపును నిలిపివేయలేదు.