API कुंजियाँ

API कुंजियाँ dAio Business तक प्रोग्रामेटिक पहुँच खोलती हैं। ये आपके अपने एप्लिकेशन, स्क्रिप्ट और सिस्टम को वेब इंटरफ़ेस से गुज़रे बिना सीधे प्लेटफ़ॉर्म से प्रश्न करने की अनुमति देती हैं — मौसम, वायु गुणवत्ता, पराग, समुद्री परिस्थितियाँ, क्षेत्रीय बुद्धिमत्ता। यह आपके एकीकरणों को औद्योगीकृत करने का प्रवेश बिंदु है: किसी ERP को डेटा देना, किसी व्यावसायिक प्रक्रिया को सक्रिय करना, अपने स्वयं के डैशबोर्ड में पूर्वानुमान प्रदर्शित करना।

प्रत्येक कुंजी आपके संगठन की ओर से कॉल को प्रमाणित करती है और उसके अधिकार विरासत में लेती है। वेबहुक के साथ संयुक्त होकर, यह आपको एक पूर्ण चैनल देती है: आप API के माध्यम से माँग पर dAio से प्रश्न करते हैं, और dAio वेबहुक के माध्यम से वास्तविक समय में आपको सूचित करता है।

सुझाव: प्रत्येक उपयोग के लिए एक अलग कुंजी बनाएँ (एक सेवा, एक परिवेश, एक भागीदार)। आप दूसरों को बाधित किए बिना एक को निरस्त कर सकते हैं और सटीक रूप से ट्रैक कर सकते हैं कि कौन-सा एकीकरण क्या उपभोग करता है।

API कुंजी किस काम आती है

आवश्यकता	API कुंजी आपको यह करने देती है…
एकीकरण	मानवीय हस्तक्षेप के बिना dAio को अपने सूचना तंत्र (ERP, CMMS, BI) से जोड़ना।
स्वचालन	निर्धारित कार्य चलाना (दैनिक पूर्वानुमान पुनर्प्राप्ति, जोखिम स्कोरिंग)।
वितरण	अपने स्वयं के एप्लिकेशन या पोर्टल में dAio डेटा प्रदर्शित करना।
नियंत्रित साझाकरण	किसी भागीदार को उपयोगकर्ता खाता बनाए बिना सीमित और निरस्त-योग्य पहुँच देना।

जानकारी: API पहुँच केवल सशुल्क योजनाओं के लिए आरक्षित है। सक्रिय सदस्यता के बिना संगठन को प्रत्येक कॉल पर 403 प्रतिक्रिया (« API access requires a paid plan ») प्राप्त होती है।

कुंजी बनाना

कुंजी बनाना संगठन के स्वामी (owner) और प्रशासकों (admin) के लिए आरक्षित है। अन्य भूमिकाएँ न तो कुंजी बना सकती हैं और न ही निरस्त कर सकती हैं।

1. सेटिंग्स > API कुंजियाँ पर जाएँ।
2. ऊपर दाईं ओर नई कुंजी पर क्लिक करें।
3. कुंजी के उपयोग की पहचान करने वाला एक वर्णनात्मक नाम दर्ज करें (उदा. « उत्पादन बैकएंड », « Power BI कनेक्टर », « भागीदार X एकीकरण »)।
4. बनाएँ पर क्लिक करें।
5. पूर्ण कुंजी एक हरे बैनर में प्रदर्शित होती है: कॉपी बटन का उपयोग करके तुरंत इसे कॉपी करें।

चेतावनी: पूर्ण कुंजी केवल एक बार, इसके बनाए जाने के क्षण में प्रदर्शित होती है। इसके बाद इसे फिर कभी प्रदर्शित नहीं किया जाता — प्लेटफ़ॉर्म केवल एक एन्क्रिप्टेड फ़िंगरप्रिंट रखता है। यदि आप इसे खो देते हैं, तो आपको एक नई कुंजी उत्पन्न करनी होगी। इसे बिना देर किए किसी सीक्रेट मैनेजर (Vault, AWS Secrets Manager, एन्क्रिप्टेड परिवेश चर) में संग्रहीत करें।

बनाए जाने के बाद, कुंजी सूची में अपने नाम, अपने उपसर्ग (पहले कुछ वर्ण, इसे प्रकट किए बिना पहचानने के लिए), एक स्थिति संकेतक (हरा = सक्रिय, लाल = निरस्त) और अपनी अंतिम उपयोग तिथि के साथ दिखाई देती है।

कुंजी का उपयोग करना

dAio API के प्रत्येक अनुरोध में आपकी कुंजी X-API-Key HTTP हेडर में शामिल होनी चाहिए। API का आधार https://api-dev.daio.app है, और B2B एंडपॉइंट /api/v1/ से उपसर्गित हैं।

curl -H "X-API-Key: AAPKI_API_KUNJI" \
  "https://api-dev.daio.app/api/v1/weather/current?lat=48.8566&lon=2.3522"

चेतावनी: अपेक्षित हेडर वास्तव में X-API-Key है, न कि Authorization: Bearer। कोई अमान्य, निरस्त या किसी अन्य हेडर में भेजी गई कुंजी 401 प्रतिक्रिया (« Invalid API key ») लौटाती है।

एंडपॉइंट की पूरी सूची (मौसम, प्रति घंटा पूर्वानुमान, वायु गुणवत्ता, पराग, समुद्री, बैच प्रसंस्करण) और प्रतिक्रियाओं के प्रारूप के लिए API तकनीकी दस्तावेज़ देखें।

दर सीमाएँ

सेवा की स्थिरता सुनिश्चित करने के लिए, प्रत्येक कुंजी एक प्रति घंटा दर सीमा के अधीन है। काउंटर प्रत्येक कुंजी के लिए अलग होता है और हर घंटे रीसेट होता है।

योजना	प्रति घंटा अनुरोध
निःशुल्क / बिना सदस्यता	कोई API पहुँच नहीं
Solo · Team · Enterprise (dAio Business)	20,000

जब सीमा तक पहुँच जाती है, तो API एक 429 प्रतिक्रिया (« Rate limit exceeded ») लौटाता है, साथ में एक Retry-After हेडर होता है जो पुनः प्रयास करने से पहले प्रतीक्षा अवधि बताता है।

जानकारी: यह प्रति घंटा सीमा आपकी योजना में शामिल मासिक अनुरोध कोटा से अलग है। प्रति योजना कोटा का विवरण सदस्यता अनुभाग में देखें।

कुंजी का रोटेशन करना

रोटेशन किसी कुंजी को उसके नाम और सूची में उसकी स्थिति को बनाए रखते हुए पुनः उत्पन्न करता है। अपने संपूर्ण एकीकरण को पुनः कॉन्फ़िगर किए बिना समय-समय पर अपने रहस्यों को नवीनीकृत करने के लिए इसका उपयोग करें।

1. सूची में, कुंजी के सामने रोटेशन आइकन (वृत्ताकार तीर) पर क्लिक करें।
2. ऑपरेशन की पुष्टि करें।
3. नया मान केवल एक बार प्रदर्शित होता है — तुरंत इसे कॉपी करें।
4. इस नए मान के साथ अपने एप्लिकेशन अपडेट करें।

सुझाव: हर 90 दिनों में एक रोटेशन निर्धारित करें, और रहस्यों तक पहुँच रखने वाले किसी सहयोगी के जाने के बाद या रिसाव के संदेह की स्थिति में व्यवस्थित रूप से।

कुंजी निरस्त करना

किसी समझौता की गई या अप्रयुक्त कुंजी की पहुँच काटने के लिए:

1. सूची में, कुंजी के सामने हटाएँ आइकन (कूड़ेदान) पर क्लिक करें।
2. निरस्तीकरण की पुष्टि करें।

निरस्तीकरण तत्काल और अपरिवर्तनीय है। निरस्त की गई कुंजी का उपयोग करने वाला कोई भी अनुरोध तुरंत 401 प्रतिक्रिया प्राप्त करेगा। कुंजी सूची में निरस्त चिह्नित, इतिहास के प्रयोजन हेतु दृश्यमान रहती है।

कुंजियों की सुरक्षा

एक API कुंजी पासवर्ड के समतुल्य है: जो भी इसे धारण करता है वह आपके संगठन के अधिकारों के साथ API से प्रश्न कर सकता है।

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

• कुंजियों को किसी सीक्रेट मैनेजर या परिवेश चर में संग्रहीत करें, कभी भी कोड में हार्ड-कोडेड नहीं।
• उन्हें क्लाइंट पक्ष (वेब ऐप, मोबाइल, ब्राउज़र JavaScript) पर उजागर न करें: एक API कॉल आपके सर्वर से उत्पन्न होनी चाहिए।
• विभाजित करें: प्रति परिवेश (उत्पादन, परीक्षण) और प्रति उपयोग एक कुंजी।
• अंतिम उपयोग तिथि की निगरानी करें: लंबे समय से निष्क्रिय कुंजी निरस्त करने योग्य कुंजी है।

सर्वोत्तम अभ्यास

• प्रत्येक कुंजी को उसके उपयोग और परिवेश के अनुसार स्पष्ट रूप से नाम दें ताकि एक नज़र में पहचाना जा सके कि यह क्या संचालित करती है।
• न्यूनतम विशेषाधिकार लागू करें: अपने सभी एकीकरणों द्वारा साझा की गई एकल कुंजी के बजाय समर्पित और निरस्त-योग्य कुंजियाँ बनाएँ।
• हर 90 दिनों में रोटेशन को स्वचालित करें और इसे अपनी सहयोगी विदाई प्रक्रियाओं में एकीकृत करें।
• क्लाइंट पक्ष पर 429 को संभालें: Retry-After हेडर का सम्मान करें और अनुरोधों को लगातार दागने के बजाय अपनी कॉल को सुचारू करें।
• समझौता किए जाने के संदेह वाली किसी भी कुंजी को तुरंत निरस्त करें — निरस्तीकरण बिना देरी के प्रभावी होता है।
• आंतरिक रूप से दस्तावेज़ करें कि कौन-सी कुंजी किस काम आती है और इसके लिए कौन ज़िम्मेदार है, ताकि सुरक्षा ऑडिट निश्चिंत रहें।

सुझाव: एक पूर्ण एकीकरण के लिए अपनी API कुंजियों को वेबहुक से जोड़ें — माँग पर dAio से प्रश्न करें, और dAio को वास्तविक समय में घटनाओं की सूचना देने दें।