प्रमाणीकरण
हर API अनुरोध एक API कुंजी से प्रमाणित होता है, जिसे Authorization हेडर में बेयरर टोकन के रूप में भेजा जाता है:
curl https://us1.platform.bird.com/v1/email/messages \
-H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."कुंजियाँ वर्कस्पेस तक सीमित होती हैं: कुंजी आपके वर्कस्पेस के रूप में प्रमाणित होती है, उसमें बनाते समय चुने गए स्कोप होते हैं और वह केवल उसी वर्कस्पेस के संसाधनों तक पहुँच सकती है। कुंजियाँ बनाने, उनके स्कोप तय करने, उन्हें रोटेट करने और रद्द करने का तरीका प्रमाणीकरण और API कुंजियाँ गाइड में बताया गया है: आप उन्हें डैशबोर्ड में Platform tools > API keys के अंतर्गत बना सकते हैं, या ब्राउज़र के बिना bird api-keys create से। यह पेज वायर-स्तर के अनुबंध के बारे में है।
कुंजी का फ़ॉर्मेट
कुंजी bk_{region}_ से शुरू होती है, जो उस क्षेत्र को बताता है जहाँ कुंजी बनाई गई थी। bk_us1_ कुंजियाँ केवल https://us1.platform.bird.com पर मान्य हैं, और bk_eu1_ कुंजियाँ केवल https://eu1.platform.bird.com पर। आधिकारिक SDK और CLI इसी प्रीफ़िक्स से होस्ट चुनते हैं।
पूरी कुंजी केवल एक बार लौटाई जाती है, उसी प्रतिक्रिया में जो उसे बनाती है। प्लेनटेक्स्ट कुंजी दोबारा प्राप्त नहीं की जा सकती, और डैशबोर्ड केवल एक छोटा key_prefix (पहले 15 अक्षर) दिखाता है। कुंजी खो जाए तो उसे रद्द करें और नई कुंजी बनाएँ।
विफलता की प्रतिक्रियाएँ
सभी विफलताएँ मानक त्रुटि प्रतिक्रिया का उपयोग करती हैं।
| स्थिति | कब |
|---|---|
401 | Authorization हेडर मौजूद नहीं है, कुंजी गलत रूप में है या अज्ञात है, या कुंजी रद्द कर दी गई है। |
403 | कुंजी मान्य है, लेकिन उसमें वह स्कोप नहीं है जिसकी एंडपॉइंट को ज़रूरत है। |
421 | कुंजी का क्षेत्र होस्ट से मेल नहीं खाता, जैसे us1.platform.bird.com पर भेजी गई bk_eu1_... कुंजी। |
421 Misdirected Request बॉडी (त्रुटि प्रकार misdirected_error, कोड E01010) सही क्षेत्रीय होस्ट बताती है, ताकि क्लाइंट गलती पहचानकर बिना अनुमान लगाए अनुरोध दोबारा भेज सके। बेस URL और क्षेत्र देखें।
डैशबोर्ड सत्र API कुंजियाँ नहीं हैं
Bird डैशबोर्ड API कुंजियों का उपयोग नहीं करता: लॉग इन करने वाले व्यक्ति को एक सत्र कुकी मिलती है, जो उसकी अपनी उपयोगकर्ता अनुमतियों तक सीमित होती है। प्रोग्रामेटिक API इंटरफ़ेस पर सत्र कुकी स्वीकार नहीं की जातीं, और डैशबोर्ड API कुंजियाँ स्वीकार नहीं करता। सर्वर वर्कलोड हमेशा API कुंजियों का उपयोग करते हैं।
संबंधित
- प्रमाणीकरण और API कुंजियाँ गाइड: कुंजियाँ बनाना, उनका स्कोप तय करना, उन्हें रोटेट करना और रद्द करना
- बेस URL और क्षेत्र: क्षेत्रीय होस्ट और क्षेत्र मॉडल
- त्रुटियाँ: त्रुटि प्रतिक्रिया और त्रुटियों की सूची
संबंधित संसाधन
इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।