OAuth સાથે કનેક્ટ કરો

API કી શેર કર્યા વિના MCP ક્લાયન્ટ્સ અને ThunderPhone CLIને અધિકૃત કરો.

OAuth તમને મંજૂર હોય તેવી પરવાનગીઓ સાથે એક એપને એક ThunderPhone સંસ્થા સાથે કનેક્ટ થવા દે છે. ડિરેક્ટરી ક્લાયન્ટ્સે ડિફૉલ્ટ રૂપે OAuth નો ઉપયોગ કરવો જોઈએ. હાથેથી ગોઠવેલ બેરર ટોકનની જરૂર હોય તેવા ક્લાયન્ટ્સ માટે સંસ્થા API કીઝ ઉપલબ્ધ રહે છે.

કનેક્શન મંજૂર કરો#

તમારા MCP ક્લાયન્ટમાં કનેક્શન શરૂ કરો. ThunderPhone માં સાઇન ઇન કરો, એપનું નામ અને વિનંતી કરેલી પરવાનગીઓ તપાસો, સંસ્થા પસંદ કરો અને મંજૂર કરો પસંદ કરો. જો તમે કનેક્શન શરૂ ન કર્યું હોય અથવા એપ પર વિશ્વાસ ન હોય, તો નકારો પસંદ કરો. એપનાં નામ તેના ડેવલપર્સ દ્વારા આપવામાં આવે છે અને તે ચકાસણીનું બેજ નથી.

વાંચન પરવાનગીઓ ઉલ્લેખિત ડેટા ઉપલબ્ધ કરાવે છે, જેમાં calls:read ની વિનંતી કરવામાં આવે ત્યારે રેકોર્ડિંગ્સ અને ટ્રાન્સક્રિપ્ટ્સનો સમાવેશ થાય છે. લેખન પરવાનગીઓ સંસાધનો બદલી અથવા કાઢી શકે છે; કૉલ્સ, અભિયાનો, ફોન ખરીદીઓ અને ડિપ્લોયમેન્ટ્સ ખર્ચ ઊભો કરી શકે છે અથવા પ્રોડક્શનને અસર કરી શકે છે. તમારી સંસ્થા ભૂમિકા યથાવત લાગુ રહે છે.

CLI કનેક્શન માટે, તમારા ટર્મિનલમાં બતાવેલી ચકાસણી લિંક ખોલો, આઠ-અક્ષરનો કોડ સરખાવો, તમારી સંસ્થા પસંદ કરો અને મંજૂર કરો. માત્ર લિંક ખોલવાથી ઍક્સેસ મળતો નથી. કોડની સમયમર્યાદા 15 મિનિટ પછી પૂરી થાય છે.

એપનું કનેક્શન તોડો#

ડેશબોર્ડમાં સંસ્થા → API કીઝ → અધિકૃત એપ્સ ખોલો અને રદ કરો પસંદ કરો. આ વર્તમાન સંસ્થા માટે તમારી પસંદ કરેલી અધિકૃતતા રદ કરે છે, જેમાં તેના ઍક્સેસ અને રિફ્રેશ ટોકન્સનો સમાવેશ થાય છે. જો તમે તેને ફરીથી અધિકૃત કરવા માંગતા હો, તો એપમાંથી ફરીથી કનેક્ટ કરો.

MCP ક્લાયન્ટ્સ માટે ડિસ્કવરી#

સર્વર URL https://api.thunderphone.com/v1/mcp નો ઉપયોગ કરો. માન્ય પ્રમાણીકરણ વિનાની વિનંતીને 401 સાથે આ મળે છે:

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"] અને userinfo એન્ડપોઇન્ટ શામેલ છે. ID ટોકન્સ અને ક્લાયન્ટ ID મેટાડેટા ડોક્યુમેન્ટ્સ (CIMD) સપોર્ટેડ નથી.

પબ્લિક ક્લાયન્ટ રજિસ્ટર કરો#

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

પરત મળેલ 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 પણ સ્વીકારવામાં આવે છે):

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 હેડર દ્વારા મોકલો. ટોકન્સને ક્યારેય URLs, લૉગ્સ, સોર્સ કંટ્રોલ અથવા ચેટમાં મૂકશો નહીં.

રિફ્રેશ અને રિવોક કરો#

ટોકન એન્ડપોઇન્ટ પર 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) કૉલ કરો. સફળ પ્રતિસાદમાં આ શામેલ હોય છે:

{
  "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 કીઝ userinfo કૉલ કરી શકતા નથી. કોઈ ID ટોકન ઇશ્યૂ થતું નથી.

ઉપલબ્ધ પરવાનગીઓ#

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 ચલાવે છે. તે સમયસમાપ્ત અધિકૃતતા વિનંતીઓ અને ડિવાઇસ કોડ્સ દૂર કરે છે. સમયસમાપ્ત ઍક્સેસ ટોકન્સ, અધિકૃતતા કોડ્સ અને રિફ્રેશ-ટોકન હેશ ફક્ત તેમની ગ્રાન્ટ રદ થયા પછી અથવા સમગ્ર પરિવાર નિષ્ક્રિય થયા પછી જ દૂર કરવામાં આવે છે. વપરાઈ ગયેલા હેશ ત્યાં સુધી જાળવી રાખવામાં આવે છે જ્યાં સુધી પરિવારમાં ઉપયોગી રિફ્રેશ ટોકન, અધિકૃતતા કોડ, મંજૂર ડિવાઇસ કોડ અથવા ઍક્સેસ ટોકન હોય, જેથી ક્લીનઅપ રિપ્લે શોધને અક્ષમ ન કરી શકે.