--- title: "OAuth ile bağlanın" description: "API anahtarı paylaşmadan MCP istemcilerine ve ThunderPhone CLI'a yetki verin." --- 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: ```http 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: ```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"] } ``` 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/` 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): ```text grant_type=authorization_code client_id= code= redirect_uri= code_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/` ü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: ```json { "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.