Ana içeriğe geç

İş ortağı uygulamaları için OAuth

Bir MonoChat kullanıcısı adına çalışan iş ortağı uygulaması, otomasyon aracı ya da özel uygulama, özel fonksiyon API'sini (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) API token'ı yerine bir OAuth erişim token'ıyla çağırabilir. Kullanıcı uygulamayı bir MonoChat sayfasında onaylar, erişebileceği organizasyonları seçer ve profil ayarlarındaki Bağlı uygulamalar sekmesinden istediği zaman iptal edebilir.

API token'ları aynı uç noktada çalışmaya devam eder. OAuth, başkaları adına çalışan bir uygulama içindir: uygulama hiçbir parola ya da API token'ı görmez ve her kullanıcı erişimini kendisi kesebilir.

Uygulama kullanıcı olarak çalışır

Erişim token'ıyla yapılan bir çağrı, uygulamayı onaylayan kullanıcı olarak ve onun rolleriyle çalışır. Yalnızca organizasyonun özel metotlarını, yalnızca kullanıcının temsilci olduğu organizasyonlarda çalıştırır.

İstemci alın​

Uygulamanız için MonoChat'ten bir istemci isteyin. MonoChat istemciyi şu bilgilerle kaydeder:

  • onay sayfasının ve Bağlı uygulamalar sekmesinin gösterdiği uygulama adı;
  • birebir eşleşen yönlendirme URI'leri: https adresleri ya da localhost, 127.0.0.1 veya [::1] üzerinde http (her port);
  • isteyebileceği kapsamlar: bu API için custom-functions:run.

Bir istemci kimliği (monochat_rc_ ile başlar) ve bir istemci gizli anahtarı (monochat_cs_ ile başlar) alırsınız. Gizli anahtar yalnızca bir kez gösterilir; MonoChat yalnızca özetini saklar. Onu sunucunuzda tutun, asla bir tarayıcıda ya da mobil uygulamada değil.

Gizli anahtar saklayamayan bir uygulama (tarayıcıda ya da kullanıcının bilgisayarında çalışan bir uygulama gibi) istemci kimliği olarak, MCP istemcilerinin yaptığı gibi bir client ID metadata belgesinin URL'sini kullanabilir. Bu durumda gizli anahtar göndermez.

Uç noktalar​

https://app.monochat.ai/.well-known/oauth-authorization-server adresindeki yetkilendirme sunucusu metadata'sı tüm uç noktaları listeler. Beyaz etiketli ya da kendi sunucularınızda çalışan bir kurulumda o kurulumun kendi adresini kullanın.

AyarDeğer
Yetkilendirme uç noktasıhttps://app.monochat.ai/oauth/authorize
Token uç noktasıhttps://app.monochat.ai/oauth/token
İptal uç noktasıhttps://app.monochat.ai/oauth/revoke
Kaynakhttps://app.monochat.ai/api/custom-functions
Kapsamcustom-functions:run
İstemci doğrulamasıHTTP Basic ya da istek gövdesinde client_id ve client_secret

Kaynağın kendi metadata'sı https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions adresindedir.

Bir kullanıcıyı bağlayın​

MonoChat, PKCE (S256) ile yetkilendirme kodu akışını kullanır. Kullanıcının iki adımlı doğrulamayı (e-posta ya da doğrulama uygulamasıyla) kurmuş olması gerekir.

  1. Kullanıcıyı yetkilendirme uç noktasına response_type=code, client_id değeriniz, kaydettiğiniz bir redirect_uri, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, bir state ve code_challenge_method=S256 ile bir code_challenge göndererek yönlendirin.
  2. Kullanıcı gerekirse MonoChat'e giriş yapar. Onay sayfası uygulamanızın adını ve Sizin adınıza özel metotları çalıştırma iznini gösterir. Kullanıcı uygulamanın erişebileceği Organizasyonlar seçeneklerini belirleyebilir (hiçbiri seçilmezse tümü), 6 haneli onay kodunu girer ve İzin ver düğmesine tıklar.
  3. MonoChat kullanıcıyı code, state ve iss ile redirect_uri adresinize geri gönderir. Kullanıcı Reddet düğmesine tıklarsa bunun yerine error=access_denied gönderir.
  4. Kodu 5 dakika içinde token uç noktasında takas edin:
curl -X POST https://app.monochat.ai/oauth/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=<redirect_uri> \
-d code_verifier=<code_verifier>

Yanıt, expires_in saniye (bir saat) geçerli bir access_token (monochat_at_ ile başlar), bir refresh_token (monochat_rt_ ile başlar) ve verilen scope değerini içerir.

API'yi çağırın​

Erişim token'ını bearer token olarak gönderin:

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
DurumNe zaman
401Token bilinmiyor, süresi dolmuş ya da iptal edilmiş veya MCP sunucusu gibi başka bir kaynak için verilmiş. WWW-Authenticate başlığı kaynak metadata'sını gösterir.
403Organizasyon, kullanıcının uygulamaya izin verdiği organizasyonlardan biri değil, kullanıcının organizasyona erişimi yok ya da izin custom-functions:run içermiyor.
429Bir sınıra ulaşıldı; Retry-After içindeki saniye kadar bekleyin. Çağrılar dakika başına sayılır: izin başına 120 ve istemci başına 1.200; organizasyonun bu uç nokta için kendi sınırı da geçerlidir.

Yenileme ve iptal​

  • Yenileme: erişim token'ının süresi dolmadan token uç noktasını grant_type=refresh_token ve refresh_token ile çağırın. Her yenileme yeni bir yenileme token'ı döndürür; yenisini kullanın. Yerine yenisi verildikten bir dakikadan fazla sonra tekrar kullanılan bir yenileme token'ı izni sonlandırır.
  • Süre sonu: izin, son yenilemeden 90 gün sonra, kullanıcı onu Bağlı uygulamalar sekmesinden iptal ettiğinde ya da kullanıcı parolasını değiştirdiğinde veya sıfırladığında sona erer. Kullanıcının uygulamayı yeniden onaylaması gerekir.
  • İptal: bir kullanıcının bağlantısını kesmek için erişim ya da yenileme token'ını istemci doğrulamanızla iptal uç noktasına gönderin:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

Aynı kullanıcıyı uygulamanıza yeniden bağlamak, önceki iznin yerini alır.