प्रमाणीकरण

हर API अनुरोध एक API कुंजी से प्रमाणित होता है, जिसे Authorization हेडर में bearer टोकन के रूप में भेजा जाता है:

curl https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."

कुंजियाँ वर्कस्पेस तक सीमित होती हैं: कुंजी आपके वर्कस्पेस के रूप में प्रमाणित होती है, उसमें बनाते समय चुने गए स्कोप होते हैं और वह केवल उसी वर्कस्पेस के संसाधनों तक पहुँच सकती है। कुंजियाँ बनाने, उनके स्कोप तय करने, उन्हें रोटेट करने और रद्द करने का तरीका प्रमाणीकरण और API कुंजी गाइड में बताया गया है: आप उन्हें डैशबोर्ड में Developers > API keys के अंतर्गत बना सकते हैं, या ब्राउज़र के बिना bird api-keys create से। यह पेज वायर-स्तर के अनुबंध के बारे में है।

कुंजी का फ़ॉर्मेट

bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix

कुंजी का रूप bk_{region}_{payload}{checksum} होता है:

• bk_{region}_: प्रीफ़िक्स से क्रेडेंशियल का प्रकार और वह क्षेत्र पता चलता है जहाँ कुंजी बनाई गई थी। bk_us1_ कुंजियाँ केवल https://us1.platform.bird.com पर मान्य हैं, और bk_eu1_ कुंजियाँ केवल https://eu1.platform.bird.com पर। आधिकारिक SDK और CLI इसी प्रीफ़िक्स से होस्ट चुनते हैं। स्थिर bk_ प्रीफ़िक्स GitHub secret scanning में पंजीकृत है, इसलिए किसी सार्वजनिक रिपॉज़िटरी में लीक हुई Bird कुंजी पकड़ी जाती है और उसकी रिपोर्ट की जाती है।
• पेलोड: 128 या उससे अधिक बिट एन्ट्रॉपी वाली एक लंबी रैंडम स्ट्रिंग।
• चेकसम: आख़िरी 6 अक्षर बाकी कुंजी का चेकसम होते हैं। इससे क्लाइंट कोई भी अनुरोध भेजने से पहले ही गलत टाइप की गई या अधूरी कुंजी को स्थानीय रूप से अस्वीकार कर सकता है।

पूरी कुंजी केवल एक बार लौटाई जाती है, उसी प्रतिक्रिया में जो उसे बनाती है। प्लेनटेक्स्ट कुंजी दोबारा प्राप्त नहीं की जा सकती, और डैशबोर्ड केवल एक छोटा key_prefix (पहले 12 अक्षर) दिखाता है। कुंजी खो जाए तो उसे रद्द करें और नई कुंजी बनाएँ।

विफलता की प्रतिक्रियाएँ

सभी विफलताएँ मानक त्रुटि प्रतिक्रिया का उपयोग करती हैं।

421 Misdirected Request बॉडी (त्रुटि प्रकार misdirected_error, कोड E01010) सही क्षेत्रीय होस्ट बताती है, ताकि क्लाइंट गलती पहचानकर बिना अनुमान लगाए अनुरोध दोबारा भेज सके। बेस URL और क्षेत्र देखें।

डैशबोर्ड सत्र API कुंजियाँ नहीं हैं

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

संबंधित

• प्रमाणीकरण और API कुंजियाँ गाइड: कुंजियाँ बनाना, उनका स्कोप तय करना, उन्हें रोटेट करना और रद्द करना
• बेस URL और क्षेत्र: क्षेत्रीय होस्ट और क्षेत्र मॉडल
• त्रुटियाँ: त्रुटि प्रतिक्रिया और त्रुटियों की सूची