प्रमाणीकरण

हर API अनुरोध Authorization हेडर में bearer टोकन के रूप में पास की गई API key से प्रमाणित होता है:

कोड उदाहरण

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

Keys वर्कस्पेस-स्कोप्ड होती हैं: एक key आपके वर्कस्पेस के रूप में प्रमाणित करती है, निर्माण के समय चुने गए scopes रखती है, और केवल अपने resources तक पहुँच सकती है। Keys बनाना, scope करना, rotate करना और revoke करना Authentication & API keys गाइड में शामिल है: इन्हें dashboard में Developers > API keys के अंतर्गत बनाएँ, या बिना ब्राउज़र के bird api-keys create से बनाएँ। यह पेज वायर-लेवल कॉन्ट्रैक्ट को कवर करता है।

Key फ़ॉर्मेट

कोड उदाहरण

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

एक key bk_{region}_{payload}{checksum} होती है:

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

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

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

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

स्थिति	कब
401	Authorization हेडर गायब है, key विकृत या अज्ञात है, या key revoke कर दी गई है।
403	Key मान्य है लेकिन endpoint के लिए आवश्यक scope उसमें नहीं है।
421	Key का region होस्ट से मेल नहीं खाता, जैसे bk_eu1_... key को us1.platform.bird.com पर भेजना।

421 Misdirected Request बॉडी (error type misdirected_error, code E01010) सही regional होस्ट का नाम देती है, ताकि क्लाइंट बिना अनुमान लगाए गलती पहचान सके और दोबारा भेज सके। देखें Base URLs और regions।

Dashboard सेशन API keys नहीं हैं

Bird dashboard API keys का उपयोग नहीं करता: लॉग इन करने वाले व्यक्ति को एक session cookie मिलती है, जो उनकी अपनी user अनुमतियों तक सीमित होती है। Session cookies प्रोग्रामैटिक API surface पर स्वीकार नहीं की जातीं, और API keys dashboard द्वारा स्वीकार नहीं की जातीं। सर्वर वर्कलोड हमेशा API keys का उपयोग करते हैं।

प्रमाणीकरण

Key फ़ॉर्मेट

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

Dashboard सेशन API keys नहीं हैं

संबंधित

संबंधित संसाधन