किसी शेड्यूल्ड सेंडर को कॉन्फ़िगर करने वाला कर्मचारी चला जाए, तब भी सेंडर को काम करते रहना चाहिए। इसके विपरीत, उस कर्मचारी की ओर से काम करने वाले टूल को ऐसी पहुँच चाहिए जो उसकी अनुमतियों के अनुसार चले।
क्रेडेंशियल इसी स्वामित्व को ध्यान में रखकर चुनें। दोनों में से किसी भी क्रेडेंशियल को ब्राउज़र कोड और लॉग से दूर रखें, क्योंकि जिसके पास भी यह होगा, वह प्रमाणित अनुरोध भेजने का प्रयास कर सकता है।
हर क्रेडेंशियल से मैं क्या कर सकता हूँ?
API कुंजी किसी वर्कस्पेस की ओर से काम करती है। OAuth टोकन किसी अधिकृत टूल को एक व्यक्ति की ओर से काम करने देता है।
Bird API कुंजियाँ bk_ से शुरू होती हैं। उनकी अनुमतियाँ वर्कस्पेस की होती हैं, इसलिए बनाने वाले व्यक्ति को हटाने से वे अमान्य नहीं होतीं। केवल वही स्कोप दें जिनकी सेवा को ज़रूरत है, ताकि उजागर हुई कुंजी सीमित काम ही कर सके।
कोई कुंजी संगठन-स्तर के काम नहीं कर सकती, जैसे संगठन के सदस्यों या बिलिंग का प्रबंधन। वर्कस्पेस के और स्कोप जोड़ने से भी यह सीमा नहीं हटती।
जब आप CLI या MCP सर्वर के ज़रिए साइन इन करते हैं, तो आप किसी टूल को अपनी अनुमतियों के एक हिस्से के साथ अधिकृत करते हैं। टूल को कम अवधि वाला bt_ टोकन मिलता है। टोकन का नवीनीकरण टूल खुद करता है, इसलिए उस टोकन को किसी सेवा के सीक्रेट मैनेजर में कॉपी न करें।
किसी अधिकृत टूल को Profile > Connected apps से रद्द करें। स्कोप चुनने और वर्कस्पेस कुंजियों को व्यक्तिगत अनुमतियों से अलग पहचानने के लिए प्रमाणीकरण देखें।
मैं API कुंजी को रोटेट कैसे करूँ?
एक नई कुंजी जारी करें और पुरानी कुंजी की ओवरलैप अवधि खत्म होने से पहले उसे डिप्लॉय करें।
आप डैशबोर्ड से, bird api-keys rotate से, या api_keys_rotate MCP टूल के ज़रिए रोटेट कर सकते हैं। CLI और MCP से रोटेशन के लिए api_keys:write वाली व्यक्तिगत अनुमति चाहिए। API कुंजी को यह अनुमति नहीं दी जा सकती और वह किसी दूसरी कुंजी को रोटेट नहीं कर सकती।
रोटेशन नई कुंजी का token केवल एक बार लौटाता है। इसे तुरंत सहेजें, क्योंकि बाद में पढ़ने पर यह वापस नहीं मिलता। नई कुंजी में पुराना नाम और IP प्रतिबंध बने रहते हैं। जब तक आप नए scopes नहीं देते, अनुमतियाँ भी वही रहती हैं।
ओवरलैप अवधि तय करने के लिए grace_period सेट करें। इसका डिफ़ॉल्ट 24h है, इसलिए उसी दिन के भीतर डिप्लॉयमेंट पूरा करें। अगर पुरानी कुंजी की समाप्ति पहले की है, तो वही लागू रहती है। रोटेशन उसे कभी आगे नहीं बढ़ाता।
यदि किसी लीक हुई कुंजी को तुरंत रद्द करना है, तो grace_period: "0" का उपयोग करें। कैश किया गया सत्यापन उसे फिर भी थोड़ी देर तक स्वीकार कर सकता है, जैसा कि नीचे बताया गया है।
- रोटेशन का अनुरोध करें और लौटाया गया टोकन सहेज लें।
- ओवरलैप समाप्त होने से पहले नई कुंजी हर सेवा में डिप्लॉय करें।
- सेवा लॉग से पुष्टि करें कि नई कुंजी के साथ अनुरोध सफल हो रहे हैं।
- पुरानी कुंजी को समाप्त होने दें, या बदलाव पूरा होने पर उसे रद्द करें।
रोटेशन संदर्भ में कमांड और उसके विकल्पों का विवरण है।
रोटेशन के दौरान क्या गड़बड़ हो सकती है?
यदि प्रतिक्रिया खो जाए, तो नई कुंजी जारी हो चुकी होगी, लेकिन उसका टोकन आपके पास सहेजा नहीं होगा।
रोटेशन अनुरोध के लिए फिर से प्रयास करते समय वही Idempotency-Key उपयोग करें, ताकि Bird अपनी पिछली प्रतिक्रिया दोबारा लौटा सके। एक कुंजी केवल एक बार रोटेट की जा सकती है। वही idempotency कुंजी न देने पर रोटेशन दोहराने से 409 मिलता है। बाद में योजनाबद्ध बदलाव के लिए नई कुंजी को रोटेट करें।
रद्द की गई कुंजी रोटेट नहीं की जा सकती। यदि मूल कुंजी पहले ही रद्द हो चुकी है, तो नई कुंजी बनाएँ।
नई कुंजी की कोई समाप्ति नहीं होती, भले ही मूल कुंजी की थी। बाद में समाप्ति जोड़ी नहीं जा सकती। यदि कुंजी को किसी तय समय पर काम करना बंद करना है, तो expires_at के साथ नई कुंजी बनाएँ।
यदि डिप्लॉयमेंट में कितना समय लगेगा यह तय नहीं है, तो दूसरी कुंजी बनाएँ और ओवरलैप खुद संभालें। मूल कुंजी रद्द करने से पहले नई कुंजी डिप्लॉय करें। अनुरोध के बाद रोटेशन की ग्रेस अवधि बढ़ाई नहीं जा सकती।
निरस्तीकरण कितनी जल्दी लागू होता है?
कैश किया गया सत्यापन समाप्त होने तक, निरस्त की गई कुंजी अधिकतम पाँच सेकंड तक स्वीकार होती रह सकती है।
उस पूरी अवधि में उजागर हुई कुंजी को उपयोग योग्य मानें। निरस्तीकरण स्थायी है, इसलिए निरस्त की गई कुंजी को फिर से सक्रिय नहीं किया जा सकता। Bird ऑडिट के लिए उसका रिकॉर्ड रखता है।
सपोर्ट बातचीत में किसी कुंजी की पहचान के लिए key_prefix या fingerprint का उपयोग करें। पूरा क्रेडेंशियल कभी शामिल न करें, क्योंकि ये पहचानकर्ता एक्सेस दिए बिना कुंजी को अलग पहचानने के लिए काफ़ी हैं।
मुझे कौन सा क्रेडेंशियल चुनना चाहिए?
इस आधार पर चुनें कि वर्कलोड का मालिक कौन है और उसे किन अनुमतियों की ज़रूरत है।
- API कुंजी: ऐसी सेवा जो अपने निर्माता से स्वतंत्र रूप से काम करती रहनी चाहिए।
- OAuth अनुमति: किसी व्यक्ति की अनुमतियों के भीतर काम करने वाला CLI या एजेंट।
- रोटेशन: एक बदली हुई कुंजी, जिसे आप तय ओवरलैप अवधि के दौरान डिप्लॉय कर सकते हैं।
- समाप्ति वाली नई कुंजी: ऐसा क्रेडेंशियल जिसे किसी निश्चित समय पर काम करना बंद करना है।
संक्षेप में
सेवा क्रेडेंशियल वर्कस्पेस के होते हैं।
कुंजी बनाने वाले व्यक्ति के चले जाने पर भी कुंजी काम करती रहती है। OAuth का उपयोग करने वाला टूल उसे अधिकृत करने वाले व्यक्ति की अनुमतियों के भीतर काम करता है।
रोटेशन के ओवरलैप के दौरान डिप्लॉय करें।
डिफ़ॉल्ट रूप से पुरानी कुंजी 24 घंटे तक काम करती रहती है, जब तक कि उसकी मौजूदा समाप्ति इससे पहले न हो।
नई कुंजी जारी होते ही उसे सहेजें।
रोटेशन नया टोकन केवल एक बार लौटाता है। रोटेशन अनुरोध के लिए फिर से प्रयास करते समय वही idempotency कुंजी रखें।
रद्दीकरण लागू होने में थोड़ा समय लगता है।
कैश किया गया सत्यापन रद्द की गई कुंजी को पाँच सेकंड तक स्वीकार कर सकता है, इसलिए कुंजी लीक होने के बाद इस देरी का ध्यान रखें।