मुख्य सामग्री पर जाएं

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 में कुंजी बनाना​

  1. B1Admin में Edit Settings वाले उपयोगकर्ता के रूप में साइन इन करें।
  2. Settings → Developer → API Keys खोलें।
  3. New API Key पर क्लिक करें, उसे एक पहचानने योग्य Name दें (जैसे "Zapier — donations sync"), कुंजी के लिए आवश्यक कम से कम एक Scopes चुनें, वैकल्पिक रूप से Expires तारीख चुनें (जिस कुंजी की समाप्ति न हो, उसके लिए इसे खाली छोड़ें), और Save करें।
  4. पूरी 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 कनेक्टरबहु-किरायेदार तृतीय-पक्ष ऐप