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