OAuth ile bağlanın

API anahtarı paylaşmadan MCP istemcilerine ve ThunderPhone CLI

OAuth, bir uygulamanın onayladığınız izinlerle tek bir ThunderPhone kuruluşuna bağlanmasını sağlar. Dizin istemcileri varsayılan olarak OAuth kullanmalıdır. Manuel olarak yapılandırılmış bir Bearer token gerektiren istemciler için kuruluş API anahtarları kullanılmaya devam edilebilir.

Bağlantıyı onaylayın#

Bağlantıyı MCP istemcinizde başlatın. ThunderPhone'ta oturum açın, uygulama adını ve istenen izinleri kontrol edin, bir kuruluş seçin ve Onayla seçeneğini belirleyin. Bağlantıyı siz başlatmadıysanız veya uygulamaya güvenmiyorsanız Reddet seçeneğini belirleyin. Uygulama adları geliştiricileri tarafından sağlanır ve doğrulama rozeti değildir.

Okuma izinleri, calls:read istendiğinde kayıtlar ve transkriptler dahil olmak üzere belirtilen verileri gösterir. Yazma izinleri kaynakları değiştirebilir veya silebilir; aramalar, kampanyalar, telefon satın alımları ve yayınlamalar maliyete neden olabilir ya da üretim ortamını etkileyebilir. Kuruluş rolünüz geçerliliğini korur.

CLI bağlantısı için terminalinizde gösterilen doğrulama bağlantısını açın, sekiz karakterli kodu karşılaştırın, kuruluşunuzu seçin ve onaylayın. Bağlantıyı yalnızca açmak erişim izni vermez. Kodların süresi 15 dakika sonra dolar.

Bir uygulamanın bağlantısını kesin#

Kontrol panelinde Kuruluş → API anahtarları → Yetkili uygulamalar bölümünü açın ve İptal et seçeneğini belirleyin. Bu işlem, erişim ve yenileme tokenları dahil olmak üzere mevcut kuruluş için seçtiğiniz yetkilendirmeyi iptal eder. Yeniden yetkilendirmek isterseniz uygulamadan tekrar bağlanın.

MCP istemcileri için keşif#

Sunucu URL'si olarak https://api.thunderphone.com/v1/mcp kullanın. Geçerli kimlik doğrulaması olmayan bir istek, aşağıdakiyle birlikte 401 alır:

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

Bu belgeyi, ardından https://api.thunderphone.com/.well-known/oauth-authorization-server adresindeki yetkilendirme sunucusu meta verilerini alın. Kaynak meta verileri /.well-known/oauth-protected-resource/v1/mcp adresinde de bulunur. Uç noktaları oluşturmaya çalışmak yerine döndürülen uç noktaları kullanın. Kaynak tanımlayıcısı https://api.thunderphone.com/v1/mcp şeklindedir.

Sunucu; S256 PKCE ile yetkilendirme kodunu, döndürülen yenileme belirteçlerini, herkese açık dinamik istemci kaydını, iptali ve cihaz yetkilendirme iznini destekler. İstemci gizli anahtarları veya örtük izinler yoktur. OpenID keşfi /.well-known/openid-configuration adresinde de kullanılabilir; aynı yetkilendirme sunucusu alanlarına ek olarak subject_types_supported: ["public"] ve userinfo uç noktasını içerir. ID belirteçleri ve İstemci Kimliği Meta Veri Belgeleri (CIMD) desteklenmez.

Herkese açık bir istemci kaydedin#

POST /v1/oauth/register adresine JSON gönderin:

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

Döndürülen client_id değerini kaydedin. Yönlendirmelerde HTTPS veya 127.0.0.1 ya da localhost üzerinde HTTP kullanılmalıdır. Bağlantı noktası ve yolu dahil olmak üzere tam geri çağırım URI'sini kaydedin. Parçalar ve gömülü kimlik bilgileri reddedilir. İsteğe bağlı client_uri ve logo_uri HTTPS kullanmalıdır; ThunderPhone bunları kayıt sırasında getirmez. Kayıt için hız sınırı uygulanır. Kayıtlı istemcilerin süresi dolmaz ve bir bağlantı iptal edildiğinde kayıtlı kalırlar. HTTPS geri çağırımları arasında https://chatgpt.com/connector/oauth/<id> ve https://chatgpt.com/connector_platform_oauth_redirect bulunur. Her bağlantı kendi istemcisini kaydedebilir.

Yetkilendirme kodu#

Keşfedilen yetkilendirme uç noktasını client_id, tam kayıtlı redirect_uri, response_type=code, rastgele bir state, scope, code_challenge, code_challenge_method=S256 ve resource=https://api.thunderphone.com/v1/mcp ile açın. Doğrulama değerini, yeni ve yüksek entropili bir PKCE doğrulayıcısının dolgusu kaldırılmış base64url SHA-256 özeti olarak hesaplayın. Kodu değiştirmeden önce döndürülen state ve iss değerlerini kontrol edin. Reddetme ve protokol hataları dahil tüm yetkilendirme yanıtları, keşfedilen issuer ile tam olarak eşleşen iss değeriyle yayıncıyı belirtir. Geçersiz istemci veya geri çağırım hataları, bu geri çağırıma yönlendirme yapılmadan yerel olarak döndürülür.

Form kodlaması kullanarak POST /v1/oauth/token adresinde değişim yapın (JSON da kabul edilir):

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

İsteğe bağlı resource parametresi, hem yetkilendirme hem de belirteç isteklerinde kabul edilir (yenileme ve cihaz değişimleri dahil). Atlandığında, varsayılan olarak keşfedilen MCP kaynağı kullanılır. Mevcut olduğunda bu kaynakla tam olarak eşleşmelidir; diğer değerler invalid_target döndürür. Erişim belirteçleri bu hedef kitleyi taşır ve MCP, hedef kitlesi eksik veya farklı olan belirteçleri 401 ve bir keşif sorgulamasıyla reddeder.

Yetkilendirme istekleri ve kodlarının süresi 10 dakika sonra dolar. Her belirteç yanıtı access_token, token_type (Bearer), expires_in (varsayılan olarak 3600 saniye), refresh_token, scope, organization_id ve organization_name içerir. Erişim belirteçlerini yalnızca Authorization: Bearer başlığı üzerinden gönderin. Belirteçleri asla URL'lere, günlük kayıtlara, kaynak kontrole veya sohbete koymayın.

Yenileme ve iptal#

Belirteç uç noktasında grant_type=refresh_token, client_id, refresh_token ve resource ile yenileyin. Yeni yenileme belirtecini atomik olarak kaydedin ve eskisini kullanmayı bırakın. Yenileme belirteçlerinin süresi, başarılı bir yenileme olmadan 30 gün sonra dolar. İsteğe bağlı bir scope, verilen izinleri daraltabilir. offline_access her zaman dahil edilir ve yenileme belirteçleri her zaman verilir. scope içermeyen ilk istek yalnızca offline_access verir; bu nedenle istemciler ihtiyaç duydukları izinleri istemelidir.

Kodun yeniden kullanılması ve döndürülmüş yenileme belirtecinin yeniden kullanılması, tüm yetkilendirmeyi iptal eder. Bir istemci içindeki yenilemeleri sıralı hale getirin; başarıyla değiştirilmiş bir kimlik bilgisini yeniden oynatmak güvenli bir yeniden deneme stratejisi değildir.

Bağlantıyı kesmek için token ve client_id değerlerini POST /v1/oauth/revoke adresine gönderin. Herhangi bir belirtecin iptal edilmesi, ondan verilen tüm belirteçler dahil yetkilendirmesini iptal eder. Bilinmeyen bir belirteç, var olup olmadığını açıklamadan başarılı sonuç döndürür. Pano oturumları kendi yetkilendirmelerini GET /v1/oauth/grants üzerinden listeleyebilir ve X-ThunderPhone-Org ile kuruluş seçilerek bir yetkilendirmeyi DELETE /v1/oauth/grants/<id> üzerinden iptal edebilir.

Cihaz yetkilendirmesi#

Cihaz yetkilendirmesi önceden kaydedilmiş istemcilerle sınırlıdır; dinamik olarak kaydedilmiş istemciler unauthorized_client alır. Önceden kaydedilmiş herkese açık thunderphone-cli istemcisi cihaz yetkilendirmesini ve yenilemeyi destekler. client_id=thunderphone-cli ve scope değerlerini POST /v1/oauth/device/code adresine gönderin. Kullanıcıya user_code ve verification_uri değerlerini gösterin veya verification_uri_complete adresini açın.

Belirteç uç noktasını grant_type=urn:ietf:params:oauth:grant-type:device_code, client_id ve device_code ile, döndürülen interval süresi kadar (5 saniye) bekleyerek sorgulayın. authorization_pending durumunda devam edin. slow_down durumunda, sonraki her istek için yanıtta döndürülen yeni interval değerini (5 saniye artırılmış) kullanın. access_denied, expired_token veya başka herhangi bir hata durumunda durun. Bir cihaz kodunu asla otomatik olarak onaylamayın.

Önceden kaydedilmiş thunderphone-mcp istemcisi, herhangi bir bağlantı noktasında http://127.0.0.1/callback ve http://localhost/callback adreslerini kabul eder. Şema, ana makine, yol ve sorgu eşleşmelidir; belirteç değişiminde yetkilendirmedeki tam yönlendirme URI'si (bağlantı noktası dahil) kullanılmalıdır. Dinamik olarak kaydedilmiş istemciler, bağlantı noktası dahil tam yönlendirme URI'si eşleşmesi gerektirir. Başka bir yola ihtiyacınız varsa farklı bir geri çağırımı dinamik olarak kaydedin.

Hesap kimliği ve çalışma alanı alan adı denetimleri#

İstemcinizin ihtiyaç duyduğu işlem kapsamlarıyla birlikte hem openid email isteyin. Erişim belirtecini Bearer başlığında kullanarak keşfedilen userinfo_endpoint (GET /v1/oauth/userinfo) uç noktasını çağırın. Başarılı bir yanıt şunları içerir:

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

sub kararlı kullanıcı tanımlayıcısıdır; org_id, onay sırasında seçilen kuruluştur. Uç nokta her iki kimlik kapsamını da gerektirir ve bunlardan biri eksikse 403 döndürür. Hesabın doğrulanmış bir e-posta profili yoksa, doğrulanmamış bir e-postanın güvenilir olduğunu belirtmek yerine error=access_denied ile 403 döndürür. Geçersiz, süresi dolmuş, iptal edilmiş veya yanlış hedef kitleye sahip belirteçler 401 döndürür. İnsan oturumu belirteçleri ve kuruluş API anahtarları userinfo çağıramaz. ID belirteci verilmez.

Kullanılabilir izinler#

| Ajanlar ve ajan içe aktarımları | agents:read, agents:write | | Aramalar | calls:read, calls:write | | Telefon numaraları, engellenen arayanlar ve VoIP | numbers:read, numbers:write | | Bilgi | knowledge:read, knowledge:write | | Kampanyalar | campaigns:read, campaigns:write | | Entegrasyonlar, webhook uç noktaları, MCP sunucuları | integrations:read, integrations:write | | Sesler | voices:read | | Test senaryoları, test çalıştırmaları, doğrulama | testing:read, testing:write | | Faturalandırma | billing:read | | Hesap kimliği ve doğrulanmış e-posta | openid, email (userinfo için ikisi de gereklidir) | | Kalıcı bağlantı | offline_access (her zaman dahil edilir) |

GET, HEAD ve OPTIONS okuma kapsamlarını kullanır; diğer yöntemler yazma kapsamlarını kullanır. Ses ve faturalandırma değişiklikleri OAuth üzerinden kullanılamaz; POST /v1/voices/preview, yapılandırmasını değiştirmeden bir sesi önizlediği için voices:read kullanır. MCP araçları, temel REST işlemlerinin kapsamını uygular. Yetkilendiren kullanıcı her iki kuruluşa da ait olsa bile kuruluşlar arası aktarımlar reddedilir. API anahtarı yönetimi ve insan hesap ayarları dahil olmak üzere diğer API aileleri OAuth üzerinden kullanılamaz. Bir REST işleminde eksik izin olduğunda WWW-Authenticate: Bearer error="insufficient_scope", scope="..." ile 403 döndürülür. Geçersiz veya süresi dolmuş erişim belirteçleri 401 döndürür.

MCP araç kimlik doğrulama sinyalleri#

tools/list içindeki her araç, o aracın REST işleminin kapsamıyla birlikte securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}] içerir. Genel dokümantasyon araçları boş bir kapsam listesi kullanır ve yine de kimliği doğrulanmış bir bağlantı gerektirir.

Bir aracın kapsamı eksik olan geçerli bir belirteç, isError: true içeren bir JSON-RPC result, content içinde açıklayıcı metin ve _meta["mcp/www_authenticate"] ile HTTP 200 alır. Sonuncusu; resource_metadata, error="insufficient_scope", error_description ve gerekli scope içeren bir Bearer sorgulaması barındıran bir dizidir. Araç çalıştırılmaz. Genişletilmiş onay istemek için bu sorgulamayı kullanın. Eksik veya geçersiz kimlik doğrulama, WWW-Authenticate ile HTTP 401 döndürmeye devam eder; REST kapsam hataları ise HTTP 403 döndürmeye devam eder.

Kimlik bilgisi saklama#

API, hazırlık ve üretim ortamlarında her saat python manage.py oauth_cleanup çalıştırır. Süresi dolmuş yetkilendirme isteklerini ve cihaz kodlarını kaldırır. Süresi dolmuş erişim belirteçleri, yetkilendirme kodları ve yenileme belirteci karmaları yalnızca hibeleri iptal edildikten veya tüm aile geçerliliğini yitirdikten sonra temizlenir. Kullanılmış karmalar, ailede kullanılabilir bir yenileme belirteci, yetkilendirme kodu, onaylanmış cihaz kodu veya erişim belirteci bulunduğu sürece saklanır; böylece temizleme işlemi yeniden oynatma tespitini devre dışı bırakamaz.