प्रमाणीकरण

API संस्करण 2026-10-affable-towhee

Lingara API की हर कॉल के साथ एक एक्सेस टोकन जाता है। सर्वर इसे टोकन एंडपॉइंट पर किसी OAuth क्लाइंट की ID और सीक्रेट के बदले एक्सचेंज करके पाता है: यह OAuth 2.0 का client credentials ग्रांट है, उस सर्वर के लिए जो स्वयं अपनी ओर से काम करता है। क्लाइंट Lingara वेब ऐप के इंटीग्रेशन पेज पर बनाएँ, app.getlingara.com/admin पर।

सत्र या क्लाइंट

Lingara ऐप्स आपको एक सत्र के साथ साइन इन करते हैं, जिसके पास हर स्कोप होता है और जो आपके प्लान का भत्ता खर्च करता है। क्लाइंट अधिक सीमित होता है: उसे बनाते समय आप चुनते हैं कि उसे कौन-से स्कोप की अनुमति है, और उसे मिलने वाले हर एक्सेस टोकन में केवल वही स्कोप होते हैं जो वह माँगता है।

तीन मान

क्लाइंट ID lgr_cid_ से शुरू होती है और टोकन एंडपॉइंट पर क्लाइंट की पहचान बताती है। यह सीक्रेट नहीं है।

क्लाइंट सीक्रेट lgr_cs_ से शुरू होता है और केवल टोकन एंडपॉइंट पर भेजा जाता है। यह केवल एक बार दिखाया जाता है, जब आप इसे बनाते हैं: उसी समय इसे कॉपी कर लें, क्योंकि Lingara इसका केवल एक हैश संग्रहीत करता है।

एक्सेस टोकन lgr_at_ से शुरू होता है और एक घंटे तक चलता है। यह /v1/ के अंतर्गत कॉल के Authorization: Bearer हेडर में जाता है, और कहीं नहीं। उस हेडर में केवल यही मान जा सकता है: वहाँ भेजा गया क्लाइंट सीक्रेट 401 के साथ अस्वीकार कर दिया जाता है।

एक्सेस टोकन पाएँ

टोकन एंडपॉइंट पर grant_type=client_credentials के साथ एक फ़ॉर्म POST करें। क्लाइंट ID और सीक्रेट या तो HTTP Basic प्रमाणीकरण से भेजें या client_id और client_secret फ़ॉर्म फ़ील्ड के रूप में, दोनों तरह से कभी नहीं। scope उन स्कोप की स्पेस से अलग की गई सूची है जिनकी क्लाइंट को अनुमति है; इसे छोड़ दें तो क्लाइंट को अनुमत हर स्कोप मिलता है। नीचे दी गई कमांड केवल usage:read माँगती है, वह स्कोप जो आगे दिए गए GET /v1/usage उदाहरण को चाहिए।

curl -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read"

जवाब में access_token, token_type (Bearer), expires_in (3600, सेकंड में) और scope होते हैं, यानी वे स्कोप जो टोकन के पास वास्तव में हैं। विफल एक्सचेंज OAuth त्रुटि रूप {error, error_description} में जवाब देता है, /v1/ के {code, error} लिफ़ाफ़े में नहीं। गलत या रद्द किया गया सीक्रेट, या हटाया गया क्लाइंट, 401 और invalid_client के साथ अस्वीकार कर दिया जाता है। ऐसा स्कोप जिसे क्लाइंट माँग नहीं सकता, पूरे एक्सचेंज को 400 और invalid_scope के साथ अस्वीकार करवा देता है; उसे कभी चुपचाप सीमित नहीं किया जाता।

किसी दूसरे Lingara उपयोगकर्ता की ओर से काम करें

किसी दूसरे Lingara उपयोगकर्ता की ओर से काम करने वाला ऐप ऑथराइज़ेशन कोड ग्रांट का उपयोग करता है। उपयोगकर्ता के ब्राउज़र को ऑथराइज़ेशन URL पर response_type=code, client_id, आपके पंजीकृत किसी URI से बिल्कुल मेल खाने वाले redirect_uri, scope, state और एक S256 code_challenge के साथ भेजें। उपयोगकर्ता Lingara का सहमति पेज देखता है और code, state और iss के साथ आपके redirect_uri पर लौटता है। कोड का उपयोग करने से पहले जाँच लें कि state वही है जो आपने भेजा था और iss https://api.getlingara.com है।

PKCE आवश्यक है

हर क्लाइंट PKCE का उपयोग करता है, केवल S256 विधि के साथ। एक यादृच्छिक code_verifier बनाएँ, उसका SHA-256 हैश base64url-एन्कोड करके code_challenge के रूप में code_challenge_method=S256 के साथ भेजें, और एक्सचेंज के लिए वेरिफ़ायर संभाल कर रखें। बिना विधि वाला, या plain वाला अनुरोध invalid_request के साथ अस्वीकार कर दिया जाता है।

कोड एक्सचेंज करें

60 सेकंड के भीतर, क्लाइंट के रूप में प्रमाणीकरण करते हुए, टोकन एंडपॉइंट पर grant_type=authorization_code, code, वही redirect_uri और code_verifier के साथ POST करें; पब्लिक क्लाइंट केवल client_id भेजता है। जवाब में एक refresh_token भी जुड़ता है, जो lgr_rt_ से शुरू होता है। कोड lgr_ac_ से शुरू होता है और एक ही बार काम करता है: दूसरा उपयोग invalid_grant के साथ अस्वीकार कर दिया जाता है और पहले एक्सचेंज में जारी किए गए टोकन समाप्त कर देता है।

रिफ़्रेश करें

जब एक्सेस टोकन की अवधि समाप्त हो, तो फिर से क्लाइंट के रूप में प्रमाणीकरण करते हुए, टोकन एंडपॉइंट पर grant_type=refresh_token और refresh_token के साथ POST करें। हर रिफ़्रेश एक नया रिफ़्रेश टोकन लौटाता है: केवल सबसे नया रखें। अपने रिफ़्रेश एक-एक करके करें: बदले जाने के 60 सेकंड से अधिक बाद उपयोग किया गया पुराना रिफ़्रेश टोकन चोरी हुआ माना जाता है, और उस इंस्टॉल के टोकन invalid_grant के साथ समाप्त कर देता है। 30 दिनों तक उपयोग न किया गया रिफ़्रेश टोकन समाप्त हो जाता है। टोकन एंडपॉइंट प्रति पते अनुरोध सीमित करता है, इसलिए केवल तभी रिफ़्रेश करें जब टोकन की अवधि समाप्त हो जाए।

नेटिव ऐप पब्लिक क्लाइंट होते हैं

डेस्कटॉप, मोबाइल या कमांड-लाइन ऐप कोई सीक्रेट सुरक्षित नहीं रख सकता, इसलिए वह पब्लिक क्लाइंट होता है: उसके पास कोई सीक्रेट नहीं होता, वह टोकन एंडपॉइंट को केवल client_id भेजता है, और http://127.0.0.1/callback (कोई भी पोर्ट) जैसा लूपबैक रीडायरेक्ट या com.example.app:/callback जैसी निजी-उपयोग स्कीम पंजीकृत करता है। उपयोगकर्ता हर बार सहमति पेज देखता है। कोई वेब पेज क्लाइंट नहीं हो सकता: न टोकन एंडपॉइंट और न ही /v1/ किसी क्रॉस-ऑरिजिन प्रीफ़्लाइट का जवाब देते हैं।

जब उपयोगकर्ता आपका ऐप हटाए

उपयोगकर्ता किसी भी समय कनेक्टेड ऐप्स में जाकर, या यदि उसने आपका ऐप इंस्टॉल किया है तो उसे अनइंस्टॉल करके, आपका ऐप हटा सकता है, और उसकी अगली कॉल 401 के साथ विफल होती है। जब उपयोगकर्ता आपके ऐप से साइन आउट करे, तो रिवोकेशन एंडपॉइंट पर उसका रिफ़्रेश टोकन रद्द करें, जिससे उस इंस्टॉल के टोकन समाप्त हो जाते हैं।

जब टोकन की अवधि समाप्त हो

एक घंटे बाद, /v1/ कोड unauthorized और invalid_token से शुरू होने वाली त्रुटि के साथ 401 लौटाता है। जब किसी कॉल को 401 मिले, या expires_in समाप्त होने से ठीक पहले, फिर से एक्सचेंज करें और कॉल को एक बार दोहराएँ। यदि एक्सचेंज स्वयं invalid_client या invalid_scope के साथ विफल हो, तो क्लाइंट या उसका सीक्रेट हटाया, रद्द या सीमित किया गया है: रुकें और इसे इंटीग्रेशन पेज पर ठीक करें, क्योंकि दोहराने से सफलता नहीं मिल सकती। कॉल के बीच टोकन को संभाल कर रखें: टोकन एंडपॉइंट प्रति क्लाइंट और प्रति पते एक्सचेंज सीमित करता है, और हर कॉल पर एक्सचेंज करने वाला प्रोग्राम घंटे के भीतर 429 और rate_limited के साथ अस्वीकार कर दिया जाता है (Retry-After की प्रतीक्षा करें)। इस ग्रांट में कोई रिफ़्रेश टोकन नहीं है: सीक्रेट को फिर से एक्सचेंज किया जाता है।

एक्सेस टोकन केवल API रूट तक पहुँचते हैं

एक्सेस टोकन केवल /v1/ के अंतर्गत आने वाले रूट पर काम करता है। किसी अन्य Lingara रूट पर भेजे जाने पर यह 401 के साथ अस्वीकार कर दिया जाता है, और बॉडी api_token_not_accepted से शुरू होती है, सादे टेक्स्ट के रूप में या किसी error फ़ील्ड के भीतर, कभी उस {code, error} लिफ़ाफ़े में नहीं जिसका उपयोग /v1/ रूट करते हैं। एक्सेस टोकन को Authorization हेडर में भेजें, जैसा नीचे दिखाया गया है।

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

स्कोप

हर ऑपरेशन को ठीक एक स्कोप चाहिए, जिसका नाम उसके पेज पर दिया गया है। उस स्कोप के बिना एक्सेस टोकन 403 और कोड insufficient_scope के साथ अस्वीकार कर दिया जाता है। ऑपरेशन कॉल करने के लिए, एक्सचेंज के समय उसका स्कोप माँगें, यदि क्लाइंट को उसकी अनुमति है। नीचे दी गई तालिका हर स्कोप और उसके द्वारा अनुमत ऑपरेशन सूचीबद्ध करती है।

कॉल का भुगतान कौन करता है

किसी क्लाइंट का बिल दो में से एक तरीके से बनता है, जो उसे बनाते समय चुना जाता है। allowance क्लाइंट अपने स्वामी का भत्ता खर्च करता है, वही भत्ता जो आपके ऐप्स खर्च करते हैं, और उसके एक्सेस टोकन भी वही खर्च करते हैं; GET /v1/usage दिखाता है कि कितना बचा है। metered क्लाइंट कोई भत्ता खर्च नहीं करता: उसका बिल प्रति क्रेडिट एक उपयोग-आधारित बिलिंग सदस्यता के ज़रिए बनता है, जिसे आप इंटीग्रेशन पेज पर सेट अप करते हैं। जैसे ही क्लाइंट या आपका खाता अपनी मासिक खर्च सीमा तक पहुँचता है, उसकी कॉल 402 और spend_cap_reached के साथ अस्वीकार की जाती हैं, और जब तक उपयोग-आधारित बिलिंग सक्रिय नहीं है, 402 और metered_billing_inactive के साथ। एक पाठ योजना 10 क्रेडिट की है, ट्यूटर की एक बारी 1 क्रेडिट की और एक शब्दावली निर्माण 3 क्रेडिट का, इसलिए GET /v1/usage जो units बताता है, वे इन भारों पर क्रेडिट में बदल जाते हैं। कोई ऐप ऑथराइज़ेशन कोड से मिले टोकन के साथ किसी दूसरे उपयोगकर्ता की ओर से जो कॉल करता है, वह, क्लाइंट का मोड चाहे जो हो, हमेशा उसी उपयोगकर्ता का भत्ता खर्च करती है।

सीक्रेट और टोकन सर्वर पर रखें

क्लाइंट सीक्रेट आपके नियंत्रण वाले सर्वर पर रहना चाहिए, कभी किसी वेब पेज, ब्राउज़र एक्सटेंशन या ऐप बंडल में नहीं, जहाँ कोई भी उसे पढ़ सकता है। नेटिव ऐप एक पब्लिक क्लाइंट होता है और उसके पास कोई सीक्रेट नहीं होता। न /v1/ और न ही टोकन एंडपॉइंट किसी क्रॉस-ऑरिजिन प्रीफ़्लाइट का जवाब देते हैं, इसलिए किसी दूसरी साइट पर चल रहा ब्राउज़र उन्हें वैसे भी कॉल नहीं कर सकता।

क्लाइंट प्रबंधित करें

इंटीग्रेशन पेज पर, app.getlingara.com/admin पर, क्लाइंट बनाएँ, उनका नाम बदलें और उन्हें हटाएँ, बदलें कि हर क्लाइंट क्या कर सकता है और वह किस संस्करण पर पिन है, और उसके सीक्रेट बनाएँ और रद्द करें। क्लाइंट को हटाने से उसके पास मौजूद हर एक्सेस टोकन तुरंत बंद हो जाता है, और हर उपयोगकर्ता द्वारा उसे दी गई अनुमति समाप्त हो जाती है। किसी सीक्रेट को रद्द करने से उस सीक्रेट के बदले एक्सचेंज किया गया हर एक्सेस टोकन तुरंत बंद हो जाता है। क्लाइंट के स्कोप सीमित करना भी तुरंत लागू होता है; उन्हें बढ़ाना, या उसका संस्करण बदलना, अगले एक्सचेंज से लागू होता है।

सीक्रेट बदलें

एक क्लाइंट के पास एक साथ दो सीक्रेट हो सकते हैं। बदलने के लिए, नया सीक्रेट बनाएँ, उसे डिप्लॉय करें, और पुराने को तब रद्द करें जब इंटीग्रेशन पेज पर उसकी अंतिम उपयोग तिथि बदलना बंद हो जाए। जिस प्रोसेस के पास नया सीक्रेट पहले से है लेकिन अब भी पुराने सीक्रेट से मिला टोकन है, उसे एक 401 मिलता है और वह फिर से एक्सचेंज करता है। किसी क्लाइंट का इकलौता सीक्रेट रद्द नहीं किया जा सकता: पहले उसका प्रतिस्थापन बनाएँ, या क्लाइंट को हटाएँ।

यदि किसी अनुवाद और अंग्रेज़ी संदर्भ में अंतर हो, तो अंग्रेज़ी संदर्भ ही मान्य है।