संगठन मास्टर कुंजियाँ

Available on requestContact your Bird representative to enable it for your organization.

जब आपके एप्लिकेशन को एक संगठन के कई वर्कस्पेस प्रबंधित करने हों, तब मास्टर कुंजी का उपयोग करें। मास्टर कुंजी वर्कस्पेस बना सकती है, उनका नाम बदल सकती है और उन्हें हटा सकती है। वह उन वर्कस्पेस में वर्कस्पेस एडमिनिस्ट्रेटर अनुमतियों के साथ HTTP API अनुरोध भी कर सकती है। वर्कस्पेस अनुरोध अपना लक्ष्य वर्कस्पेस बताते हैं, जबकि संगठन अनुरोध कुंजी से जुड़े संगठन का उपयोग करते हैं।

मास्टर कुंजियाँ प्रबंधित करने के लिए आपको संगठन का ओनर या एडमिनिस्ट्रेटर होना चाहिए। अपने संगठन के लिए मास्टर कुंजियाँ चालू करवाने के लिए अपने Bird प्रतिनिधि से संपर्क करें। किसी एक वर्कस्पेस का एक्सेस होने से मास्टर कुंजी प्रबंधन का एक्सेस नहीं मिलता।

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

मास्टर कुंजी बनाएँ

मास्टर कुंजी बनाने के लिए आपके संगठन की सीमा में एक खाली स्लॉट होना चाहिए। कुंजी रद्द करने से उसका स्लॉट खाली हो जाता है। रोटेशन किसी अतिरिक्त स्लॉट का उपयोग किए बिना कुंजी को बदल देता है, तब भी जब पुराना क्रेडेंशियल अपनी ग्रेस अवधि में मान्य रहता है। अगर आपको अधिक सीमा चाहिए, तो अपने Bird प्रतिनिधि से संपर्क करें।

1. Dashboard खोलें और अपना संगठन चुनें।
2. संगठन साइडबार में Master keys खोलें, फिर Create master key चुनें। केवल एक वर्कस्पेस होने पर Platform tools खोलें, फिर API keys के बगल में Master keys खोलें।
3. ऐसा नाम दर्ज करें जिससे एप्लिकेशन या एनवायरनमेंट की पहचान हो, जैसे Production integration।
4. Create master key चुनें और लौटाई गई कुंजी को अपने सीक्रेट मैनेजर में सहेजें।
5. डायलॉग बंद करने के लिए I've saved my key चुनें।

पूरी कुंजी केवल एक बार दिखाई देती है। आप इसे बाद में सूची से वापस नहीं पा सकते। अगर यह खो जाए, तो नई कुंजी पाने के लिए कुंजी को रोटेट करें।

मास्टर कुंजियाँ bm_ (Bird master) से शुरू होती हैं, जिसके बाद क्षेत्र आता है, उदाहरण के लिए bm_eu1_।

नई मास्टर कुंजियों की कोई समाप्ति नहीं होती। उनकी पहुँच निश्चित होती है; कुंजी बनाते समय आप अलग-अलग स्कोप नहीं चुनते। कुंजी अपने संगठन के मौजूदा और भविष्य के सभी वर्कस्पेस पर लागू होती है। कुंजी बनाने वाले व्यक्ति को हटाने से कुंजी रद्द नहीं होती।

संगठन अनुरोध भेजें

मास्टर कुंजी को बेयरर टोकन के रूप में भेजें। कुंजी आपके संगठन की पहचान करती है। कुंजी से मेल खाने वाला क्षेत्रीय API होस्ट इस्तेमाल करें: eu1 के लिए https://eu1.platform.bird.com, या us1 के लिए https://us1.platform.bird.com।

BIRD_API_URL को उस होस्ट पर सेट करें और BIRD_MASTER_KEY को अपने सीक्रेट मैनेजर से लोड करें।

संगठन ऑपरेशन कुंजी से जुड़े संगठन का इस्तेमाल करते हैं। आपको X-Organization-Id भेजने की ज़रूरत नहीं है। वर्कस्पेस बनाना फिर भी संगठन के वर्कस्पेस कोटा के अधीन रहता है।

वर्कस्पेस अनुरोध भेजें

BIRD_WORKSPACE_ID को संगठन की किसी वर्कस्पेस ID पर सेट करें। वर्कस्पेस अनुरोधों में इसे X-Workspace-Id में भेजें:

curl "$BIRD_API_URL/v1/workspace" \
  -H "Authorization: Bearer $BIRD_MASTER_KEY" \
  -H "X-Workspace-Id: $BIRD_WORKSPACE_ID"

सफल प्रतिक्रिया चुने गए वर्कस्पेस के साथ 200 लौटाती है। प्रोडक्ट अनुरोध, जैसे ईमेल संदेश पढ़ना, भी यही वर्कस्पेस हेडर इस्तेमाल करते हैं। आपको X-Organization-Id की ज़रूरत नहीं है: कुंजी पहले से अपने संगठन की पहचान करती है।

अगर आप दोनों संदर्भ हेडर भेजते हैं, तो उन्हें एक वर्कस्पेस और उसके स्वामी संगठन की पहचान करनी चाहिए। मास्टर कुंजी किसी दूसरे संगठन के वर्कस्पेस तक नहीं पहुँच सकती। किसी वर्कस्पेस को चुनने से उसके क्रेडेंशियल, कॉन्फ़िगरेशन या संसाधन किसी दूसरे वर्कस्पेस के साथ नहीं मिलते।

मास्टर कुंजियाँ HTTP अनुरोधों, Bird CLI और स्थानीय MCP सर्वर का समर्थन करती हैं। वर्कस्पेस संचालनों के लिए स्पष्ट रूप से वर्कस्पेस बताना होता है। मास्टर कुंजियाँ SMTP या SIP कनेक्शनों को प्रमाणित नहीं करतीं; उन कनेक्शनों के लिए वर्कस्पेस क्रेडेंशियल का उपयोग करें।

Bird CLI और स्थानीय MCP सर्वर आपके लिए यही हेडर भेजते हैं। BIRD_API_KEY को मास्टर कुंजी पर सेट करें, फिर संगठन के वर्कस्पेस की सूची देखें:

export BIRD_API_KEY="$BIRD_MASTER_KEY"
bird organization workspaces list

हर वर्कस्पेस कमांड में --target-workspace-id दें। CLI इसे केवल उसी कमांड के लिए X-Workspace-Id के रूप में भेजता है:

bird email list --target-workspace-id "$BIRD_WORKSPACE_ID"
bird webhooks create --url https://example.com/bird --events email.delivered \
  --target-workspace-id "$BIRD_WORKSPACE_ID"

सूची के अगले पेज और आगे के कमांड में यह फ़्लैग दोबारा दें। इसके बिना वर्कस्पेस कमांड अनुरोध भेजने से पहले ही विफल हो जाता है। --target-organization-id वैकल्पिक है और X-Organization-Id भेजता है, जो कुंजी के संगठन से मेल खाना चाहिए।

स्थानीय MCP सर्वर को bird mcp और उसी BIRD_API_KEY के साथ शुरू करें। मास्टर कुंजी के साथ वर्कस्पेस टूल हर कॉल पर target_workspace_id स्वीकार करते हैं, उदाहरण के लिए email_list के लिए {"target_workspace_id": "ws_...", "limit": 10}। हर कॉल अलग से चलती है, इसलिए दो कॉल अलग-अलग वर्कस्पेस को लक्ष्य बना सकती हैं। वर्कस्पेस चुनना केवल स्थानीय सर्वर पर उपलब्ध है; होस्ट किया गया MCP सर्वर ये इनपुट स्वीकार नहीं करता।

वर्कस्पेस API कुंजियाँ और साइन-इन किए गए CLI सेशन पहले से एक ही वर्कस्पेस में काम करते हैं। वे इन विकल्पों का उपयोग नहीं करते, और CLI तथा MCP सर्वर इन्हें नहीं दिखाते।

एक्सेस की सीमाएँ समझें

मास्टर कुंजी वर्कस्पेस बना सकती है, उनका नाम बदल सकती है और उन्हें हटा सकती है। हर वर्कस्पेस में उसके पास पूरी वर्कस्पेस एडमिनिस्ट्रेटर भूमिका होती है, जिसमें प्रोडक्ट कॉन्फ़िगरेशन, ऑटोमेशन, API कुंजियाँ और कनेक्ट किए गए इंटीग्रेशन शामिल हैं। यह संगठन का आखिरी बचा वर्कस्पेस नहीं हटा सकती। यह वर्कस्पेस API कुंजियाँ भी जारी कर सकती है, लोगों को वर्कस्पेस में आमंत्रित कर सकती है और वर्कस्पेस सदस्यता प्रबंधित कर सकती है।

मास्टर कुंजी अन्य मास्टर कुंजियों, संगठन भूमिकाओं, संगठन-भूमिका आमंत्रणों, बिलिंग फ़ंडिंग, भुगतान विधियों, SSO या सुरक्षा नीतियों को प्रबंधित नहीं कर सकती। मास्टर कुंजियाँ संगठन API तक असीमित एक्सेस नहीं देतीं। प्रोडक्ट की उपलब्धता, वर्कस्पेस सीमाएँ और हर संचालन की एक्सेस आवश्यकताएँ फिर भी लागू होती हैं।

मास्टर कुंजी रोटेट करें

1. Master keys पर, कुंजी का कार्रवाई मेनू खोलें और Rotate चुनें।
2. चुनें कि पुरानी कुंजी कब काम करना बंद करे: Immediately, After 24 hours या After 7 days। डिफ़ॉल्ट After 24 hours है।
3. Rotate master key चुनें और नई कुंजी को अपने सीक्रेट मैनेजर में सहेजें।
4. पुरानी कुंजी की ग्रेस अवधि खत्म होने से पहले अपने एप्लिकेशन को नई कुंजी इस्तेमाल करने के लिए अपडेट करें।

नई कुंजी में पुरानी कुंजी का नाम और एक्सेस बना रहता है और इसकी कोई समाप्ति नहीं होती। इसका पूरा मान केवल एक बार दिखता है। अगर पुरानी कुंजी चुनी गई ग्रेस अवधि से पहले ही समाप्त होने वाली है, तो वही पहले वाली समाप्ति लागू रहती है।

किसी कुंजी को एक ही बार रोटेट किया जा सकता है। दोबारा रोटेट करने के लिए उसकी नई कुंजी चुनें। अगर कोई कुंजी उजागर हो जाए, तो Immediately चुनें या उसे रद्द करें।

मास्टर कुंजी रद्द करें

Master keys पर कुंजी का कार्रवाई मेनू खोलें, Revoke चुनें और Revoke master key की पुष्टि करें। इसका उपयोग करने वाले एप्लिकेशन का एक्सेस समाप्त हो जाता है। रद्द करना स्थायी है, पर उसका रिकॉर्ड Show revoked keys में उपलब्ध रहता है।

अगर आपका आवंटन शून्य हो जाता है, तब भी आप मौजूदा कुंजियों को रोटेट या रद्द कर सकते हैं। आख़िरी कुंजी रद्द करने के बाद साइडबार की प्रविष्टि गायब हो जाती है और आप संगठन के Home पर लौट आते हैं। नई कुंजी बनाने के लिए आवंटन बढ़वाना ज़रूरी है।

रद्द करना आम तौर पर लगभग तुरंत लागू होता है, हालाँकि थोड़ी देरी हो सकती है। अगर आप नियमित रखरखाव के दौरान कोई कुंजी बदल रहे हैं, तो पुराना क्रेडेंशियल रद्द करने से पहले अपना एप्लिकेशन अपडेट करें।

अनुरोधों की समस्याएँ हल करें

अगले चरण

• वर्कस्पेस बनाएँ: HTTP API के ज़रिए वर्कस्पेस बनाएँ।
• वर्कस्पेस API कुंजियाँ: सीमित अनुमतियों वाले क्रेडेंशियल बनाएँ।
• बेस URL और क्षेत्र: अपने अनुरोधों के लिए API होस्ट चुनें।
• आइडेम्पोटेंट अनुरोध: समर्थित बदलावों को उनका प्रभाव दोहराए बिना फिर से प्रयास करें।