API कुंजियाँ
API कुंजियाँ (व्यक्तिगत एक्सेस टोकन) किसी सर्वर-साइड स्क्रिप्ट, किसी तृतीय-पक्ष कनेक्टर (Zapier, Make, Google Sheets), या ऐसी किसी भी जगह से B1 API पर प्रमाणीकरण करने का सबसे सरल तरीका हैं, जहाँ पूरा OAuth प्रवाह अनावश्यक हो। एक कुंजी किसी विशेष चर्च के किसी विशेष व्यक्ति से बंधी होती है और उस व्यक्ति की अनुमतियाँ विरासत में लेती है, जिन्हें एक वैकल्पिक स्कोप सेट द्वारा सीमित किया जा सकता है।
शुरू करने से पहले
- कुंजियाँ वह चर्च प्रशासक बनाता और प्रबंधित करता है जिसके पास Edit Settings अनुमति है
- कच्ची कुंजी बनाते समय एक बार दिखाई जाती है -- इसे तुरंत किसी सुरक्षित जगह पर संग्रहीत करें
- सभी API अनुरोधों के लिए HTTPS का उपयोग अनिवार्य है
कुंजी का प्रारूप
एक B1 API कुंजी ऐसी दिखती है:
cak_<prefix>.<secret>
cak_-- स्थिर पहचानकर्ता (प्रमाणीकरण परत जिस API कुंजी उपसर्ग से मेल खाती है)<prefix>-- 8-अक्षर का सार्वजनिक खोज खंड<secret>-- 48-अक्षर का गुप्त मान; सर्वर पर केवल एक SHA-256 हैश संग्रहीत होता है
पूरी कुंजी मानक bearer हेडर में सर्वर को भेजी जाती है:
Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7
API प्रमाणीकरण परत cak_ से शुरू होने वाले किसी भी टोकन को API-कुंजी पथ पर भेजती है, गुप्त मान का हैश बनाती है, उपसर्ग से उसे खोजती है, और कुंजी के व्यक्ति की वर्तमान अनुमतियाँ हल करती है -- इसलिए B1Admin में किसी अनुमति को रद्द करने का प्रभाव अगले ही अनुरोध पर होता है, और कुंजी भूमिका से कभी असंगत नहीं होती।
B1Admin में कुंजी बनाना
- B1Admin में Edit Settings वाले उपयोगकर्ता के रूप में साइन इन करें।
- Settings → Developer → API Keys खोलें।
- New API Key पर क्लिक करें, उसे एक पहचानने योग्य Name दें (जैसे "Zapier — donations sync"), कुंजी के लिए आवश्यक कम से कम एक Scopes चुनें, वैकल्पिक रूप से Expires तारीख चुनें (जिस कुंजी की समाप्ति न हो, उसके लिए इसे खाली छोड़ें), और Save करें।
- पूरी
cak_…कुंजी एक संवाद में एक बार दिखाई जाती है। संवाद बंद करने से पहले इसे अपने इंटीग्रेशन की कॉन्फ़िग में कॉपी करें -- इसे बाद में वापस पाने का कोई तरीका नहीं है। आप हमेशा एक नई कुंजी बना सकते हैं।
स्कोप
स्कोप किसी कुंजी के कार्यों को सीमित करता है -- यह उस अंतर्निहित व्यक्ति के पास न होने वाली अनुमति कभी नहीं दे सकता। खाली / कोई स्कोप न होने का अर्थ है कि कुंजी के पास व्यक्ति का पूरा अनुमति सेट होता है; B1Admin हमेशा कम से कम एक स्कोप माँगता है, इसलिए बिना स्कोप वाली कुंजी केवल API के माध्यम से बनाई जा सकती है।
| स्कोप | अनुमति देता है |
|---|---|
people:read / people:write | लोगों, परिवारों, समूह सदस्यों को देखना / संपादित करना |
groups:read / groups:write | समूहों और उनकी सदस्यता को देखना / संपादित करना |
donations:read / donations:write | दानों को देखना / दर्ज करना |
attendance:read / attendance:write | उपस्थिति, सत्र, चेक-इन को देखना / दर्ज करना |
forms:write | फ़ॉर्म प्रबंधित करना (पढ़ने की पहुँच write में निहित है) |
content:read / content:write | वेबसाइट सामग्री, पंजीकरण, स्ट्रीमिंग को देखना / संपादित करना |
messaging:read / messaging:write | संदेशन पढ़ना; write में SMS भेजना भी शामिल है |
roles:read / roles:write | भूमिका परिभाषाओं को देखना / संपादित करना |
settings:read / settings:write | चर्च सेटिंग्स को देखना / संपादित करना (प्रोग्रामेटिक रूप से वेबहुक पंजीकृत करने के लिए आवश्यक) |
workflows:read / workflows:write | वर्कफ़्लो और कार्य देखना / वर्कफ़्लो चलाना और संपादित करना। वर्कफ़्लो चलाने से ईमेल और टेक्स्ट भेजे जा सकते हैं, वेबहुक चल सकते हैं, और समूह सदस्यता बदल सकती है |
offline_access | लंबी अवधि के रिफ़्रेश टोकन की अनुमति (केवल OAuth प्रवाह के लिए -- API कुंजियों पर इसका कोई प्रभाव नहीं) |
write स्कोप में मिलते-जुलते read स्कोप निहित होते हैं। सर्वर और डोमेन-एडमिन अनुमतियाँ जानबूझकर स्कोप के रूप में उजागर नहीं की गई हैं -- एक सीमित क्रेडेंशियल कभी भी साइट प्रशासन तक ऊँचा नहीं हो सकता।
यदि आप कुंजी का उपयोग वेबहुक पंजीकृत करने के लिए करेंगे (जैसे Zapier या Make इंटीग्रेशन के लिए), तो कुंजी के पास settings:write होना आवश्यक है। केवल people:read वाली कुंजी POST /membership/webhooks पर चुपचाप 403 देती है।
कुंजी का उपयोग
यह किसी भी bearer टोकन जैसा ही है -- हर प्रमाणित एंडपॉइंट API कुंजियों को ठीक वैसे ही स्वीकार करता है जैसे JWT को:
curl https://api.churchapps.org/membership/people \
-H "Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7"
जिस अनुरोध की कुंजी के पास पर्याप्त स्कोप नहीं हैं, वह उसी आकार की 403 Forbidden प्रतिक्रिया देता है जो किसी भी अनुमति-अस्वीकृत त्रुटि के लिए उपयोग होता है।
API के माध्यम से कुंजियाँ प्रबंधित करना
सभी एंडपॉइंट Membership मॉड्यूल के /membership/apiKeys पथ के अंतर्गत हैं और उन्हें Edit Settings वाले चर्च प्रशासक से JWT (API कुंजी नहीं) चाहिए।
| मेथड और पथ | उद्देश्य |
|---|---|
GET /membership/apiKeys | चर्च की कुंजियों की सूची (कोई गुप्त मान नहीं -- केवल id, name, prefix, scopes, lastUsedAt, expiresAt, createdAt) |
GET /membership/apiKeys/scopes | सभी उपलब्ध स्कोप नामों की सूची -- कुंजी-निर्माण UI के लिए |
POST /membership/apiKeys | नई कुंजी बनाएँ। बॉडी: { "name": "...", "scopes": ["people:read"] }। प्रतिक्रिया में कच्ची cak_… कुंजी एक बार शामिल होती है। |
DELETE /membership/apiKeys/:id | कुंजी रद्द करें -- अगले अनुरोध पर प्रभावी |
रद्द की गई कुंजी तुरंत समाप्त हो जाती है -- कोई ग्रेस अवधि नहीं होती।
सर्वोत्तम प्रथाएँ
- हर इंटीग्रेशन के लिए एक कुंजी। यदि कुछ से समझौता होता है, तो आप बाकी को तोड़े बिना केवल एक कुंजी रद्द करते हैं।
- वे सबसे सीमित स्कोप बनाएँ जो काम करें। Google Sheets निर्यात को केवल
people:readचाहिए,settings:writeनहीं। - कुंजी को किसी वास्तविक स्टाफ़ सदस्य के बजाय एक सेवा खाते से बाँधें। यदि कोई स्टाफ़ सदस्य छोड़ता है, तो उसकी B1 पहुँच समाप्त होती है -- और उसकी पहचान के तहत बनाई गई सभी कुंजियाँ भी।
- कुंजियों को सीक्रेट मैनेजर में रखें (आपके होस्टिंग प्रदाता के environment variables, AWS Secrets Manager, आदि) -- कभी भी सोर्स कंट्रोल में नहीं।
- संभावित एक्सपोज़र का संदेह हो तो कुंजियाँ रोटेट करें: एक नई कुंजी बनाएँ, इंटीग्रेशन अपडेट करें, फिर पुरानी कुंजी हटाएँ।
OAuth से अंतर
API कुंजियाँ तब उपयुक्त हैं जब आपका चर्च इंटीग्रेशन का अकेला उपयोगकर्ता है। ऐसे कनेक्टर के लिए जिसे कई चर्चों तक हर एक की स्पष्ट सहमति से पहुँच चाहिए -- जैसे B1 समुदाय में साझा किया गया SaaS ऐप -- इसके बजाय OAuth और Connected Apps का उपयोग करें।
| API कुंजी | OAuth | |
|---|---|---|
| इसे कौन इंस्टॉल करता है | एक चर्च प्रशासक | हर चर्च प्रशासक ऐप को अधिकृत करता है |
| प्रमाणीकरण हेडर | Authorization: Bearer cak_… | Authorization: Bearer <jwt> |
| टोकन की अवधि | रद्द होने तक | एक्सेस ≈ 7 दिन, रिफ़्रेश ≈ 90 दिन |
| सबसे उपयुक्त | आंतरिक स्क्रिप्ट, Zapier/Make/Sheets कनेक्टर | बहु-किरायेदार तृतीय-पक्ष ऐप |