मुख्य कंटेंट तक स्किप करें

पार्टनर ऐप के लिए OAuth

कोई पार्टनर ऐप, ऑटोमेशन टूल या कस्टम ऐप जो किसी MonoChat उपयोगकर्ता के लिए काम करता है, कस्टम फ़ंक्शन API (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) को API टोकन के बजाय OAuth एक्सेस टोकन से कॉल कर सकता है। उपयोगकर्ता MonoChat के एक पेज पर ऐप को स्वीकृत करता है, वे संगठन चुनता है जिन तक ऐप पहुँच सकता है, और प्रोफ़ाइल सेटिंग्स में कनेक्टेड ऐप से कभी भी इसे रद्द कर सकता है।

API टोकन उसी endpoint पर काम करते रहते हैं। OAuth उस ऐप के लिए है जो दूसरे लोगों की ओर से काम करता है: वह कभी पासवर्ड या API टोकन नहीं देखता, और हर उपयोगकर्ता खुद उसे डिस्कनेक्ट कर सकता है।

ऐप उपयोगकर्ता के रूप में काम करता है

एक्सेस टोकन से की गई कॉल उस उपयोगकर्ता के रूप में, उसकी भूमिकाओं के साथ चलती है जिसने ऐप स्वीकृत किया। यह केवल संगठन के कस्टम मेथड चलाती है, और केवल उन संगठनों में जहाँ उपयोगकर्ता एजेंट है।

क्लाइंट प्राप्त करें​

अपने ऐप के लिए MonoChat से क्लाइंट माँगें। MonoChat उसे इनके साथ पंजीकृत करता है:

  • ऐप का नाम, जिसे स्वीकृति पेज और कनेक्टेड ऐप दिखाते हैं;
  • उसके रीडायरेक्ट URI, बिल्कुल मेल खाते हुए: https पते, या localhost, 127.0.0.1 या [::1] पर http (कोई भी पोर्ट);
  • वे स्कोप जो वह माँग सकता है: इस API के लिए custom-functions:run।

आपको एक क्लाइंट ID (monochat_rc_ से शुरू) और एक क्लाइंट सीक्रेट (monochat_cs_ से शुरू) मिलता है। सीक्रेट केवल एक बार दिखाया जाता है; MonoChat केवल उसका हैश रखता है। इसे अपने सर्वर पर रखें, कभी ब्राउज़र या मोबाइल ऐप में नहीं।

जो ऐप सीक्रेट सुरक्षित नहीं रख सकता, जैसे ब्राउज़र में या उपयोगकर्ता के कंप्यूटर पर चलने वाला ऐप, वह MCP क्लाइंट की तरह क्लाइंट ID मेटाडेटा दस्तावेज़ का URL क्लाइंट ID के रूप में इस्तेमाल कर सकता है। तब वह कोई सीक्रेट नहीं भेजता।

Endpoints​

https://app.monochat.ai/.well-known/oauth-authorization-server पर ऑथराइज़ेशन सर्वर मेटाडेटा सभी endpoints की सूची देता है। व्हाइट-लेबल या खुद होस्ट किए गए इंस्टॉलेशन पर उसी इंस्टॉलेशन का पता इस्तेमाल करें।

सेटिंगमान
ऑथराइज़ेशन endpointhttps://app.monochat.ai/oauth/authorize
टोकन endpointhttps://app.monochat.ai/oauth/token
रद्दीकरण endpointhttps://app.monochat.ai/oauth/revoke
रिसोर्सhttps://app.monochat.ai/api/custom-functions
स्कोपcustom-functions:run
क्लाइंट प्रमाणीकरणHTTP Basic, या अनुरोध बॉडी में client_id और client_secret

रिसोर्स का अपना मेटाडेटा https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions पर है।

उपयोगकर्ता को कनेक्ट करें​

MonoChat PKCE (S256) के साथ ऑथराइज़ेशन कोड फ़्लो इस्तेमाल करता है। उपयोगकर्ता के पास दो-चरणीय सत्यापन (ईमेल या ऑथेंटिकेटर ऐप से) सेट होना चाहिए।

  1. उपयोगकर्ता को ऑथराइज़ेशन endpoint पर response_type=code, अपनी client_id, पंजीकृत redirect_uri, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, एक state और code_challenge_method=S256 के साथ एक code_challenge के साथ भेजें।
  2. ज़रूरत हो तो उपयोगकर्ता MonoChat में साइन इन करता है। स्वीकृति पेज आपके ऐप का नाम और आपकी ओर से कस्टम मेथड चलाना दिखाता है। उपयोगकर्ता वे संगठन चुन सकता है जिन तक ऐप पहुँच सकता है (कोई न चुने तो सभी), 6 अंकों का पुष्टि कोड डालता है और अनुमति दें पर क्लिक करता है।
  3. MonoChat उपयोगकर्ता को code, state और iss के साथ आपके redirect_uri पर वापस भेजता है। अगर उपयोगकर्ता अस्वीकार करें पर क्लिक करे, तो इसके बजाय error=access_denied भेजा जाता है।
  4. कोड को 5 मिनट के भीतर टोकन endpoint पर बदलें:
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>

जवाब में expires_in सेकंड (एक घंटा) के लिए मान्य access_token (monochat_at_ से शुरू), एक refresh_token (monochat_rt_ से शुरू) और दिया गया scope होता है।

API कॉल करें​

एक्सेस टोकन को bearer टोकन के रूप में भेजें:

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
स्टेटसकब
401टोकन अज्ञात, समाप्त या रद्द है, या किसी दूसरे रिसोर्स, जैसे MCP सर्वर, के लिए जारी हुआ है। WWW-Authenticate हेडर रिसोर्स मेटाडेटा की ओर इशारा करता है।
403संगठन उनमें से नहीं है जिनकी उपयोगकर्ता ने ऐप को अनुमति दी, उपयोगकर्ता की संगठन तक पहुँच नहीं है, या अनुमति में custom-functions:run नहीं है।
429कोई सीमा पूरी हो गई; Retry-After में दिए सेकंड तक प्रतीक्षा करें। कॉल प्रति मिनट गिनी जाती हैं: प्रति अनुमति 120 और प्रति क्लाइंट 1,200, इस endpoint के लिए संगठन की अपनी सीमा के अलावा।

रिफ्रेश और रद्द करना​

  • रिफ्रेश: एक्सेस टोकन समाप्त होने से पहले grant_type=refresh_token और refresh_token के साथ टोकन endpoint कॉल करें। हर रिफ्रेश नया रिफ्रेश टोकन लौटाता है; नया इस्तेमाल करें। बदले जाने के एक मिनट से अधिक बाद दोबारा इस्तेमाल हुआ रिफ्रेश टोकन अनुमति समाप्त कर देता है।
  • समाप्ति: अनुमति अंतिम रिफ्रेश के 90 दिन बाद, जब उपयोगकर्ता इसे कनेक्टेड ऐप से रद्द करे, या जब उपयोगकर्ता अपना पासवर्ड बदले या रीसेट करे, समाप्त हो जाती है। फिर उपयोगकर्ता को ऐप दोबारा स्वीकृत करना होगा।
  • रद्द करना: किसी उपयोगकर्ता को डिस्कनेक्ट करने के लिए एक्सेस या रिफ्रेश टोकन अपने क्लाइंट प्रमाणीकरण के साथ रद्दीकरण endpoint पर भेजें:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

उसी उपयोगकर्ता को आपके ऐप से फिर से कनेक्ट करने पर उसकी पिछली अनुमति बदल जाती है।