ऑथेंटिकेशन

API सर्वरों को संगठन की API कुंजियों से ऑथेंटिकेट करता है। कुंजी किसी संगठन की होती है (किसी व्यक्ति की नहीं), उसके पास अनुमतियों का एक सेट होता है, और वह ठीक एक मोड में काम करती है: test या live।

कुंजी भेजना

इनमें से कोई भी हेडर इस्तेमाल करें:

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

कुंजियाँ bf_live_… या bf_test_… जैसी दिखती हैं। कुंजी न होने पर 401 (unauthorized) मिलता है; ग़लत फ़ॉर्मैट वाली, रद्द की गई या समय-सीमा समाप्त कुंजी पर भी 401 मिलता है। कुंजियाँ अपने सर्वर पर ही रखें: इन्हें कभी ब्राउज़र या मोबाइल ऐप में न भेजें। ब्राउज़र में हस्ताक्षर के लिए इसके बजाय एक हस्ताक्षर सेशन बनाएँ।

टेस्ट और लाइव कुंजियाँ

	टेस्ट (`bf_test_…`)	लाइव (`bf_live_…`)
दस्तावेज़	`TEST` वॉटरमार्क के साथ रेंडर होते हैं	बिना वॉटरमार्क
ईमेल	सिर्फ़ आपके संगठन के सदस्यों को डिलीवर होता है	हर प्राप्तकर्ता को डिलीवर होता है
बिलिंग	मुफ़्त और असीमित, कभी गिना नहीं जाता	पूरे हुए लिफ़ाफ़े आपके प्लान में गिने जाते हैं
डेटा	इस कुंजी से बने लिफ़ाफ़े, लिंक और वेबहुक एंडपॉइंट टेस्ट मोड में होते हैं	लाइव मोड

मोड हमेशा कुंजी से तय होता है, अनुरोध से कभी नहीं: POST /v1/envelopes पर ?test_mode=true सिर्फ़ डैशबोर्ड सेशन पर लागू होता है। सूचियाँ (GET /v1/envelopes, GET /v1/signing-links) सिर्फ़ कुंजी के मोड वाले आइटम लौटाती हैं, और किसी लिफ़ाफ़े के इवेंट सिर्फ़ उसी मोड के वेबहुक एंडपॉइंट पर जाते हैं। हर लिफ़ाफ़ा और वेबहुक पेलोड बताता है कि वह किस मोड में है (testMode)।

कुंजियाँ बनाना और रद्द करना

कुंजियों का प्रबंधन डैशबोर्ड में, सेटिंग्स › API कुंजियाँ में, वे सदस्य करते हैं जिनके पास apikey:manage अनुमति है (ओनर और एडमिन)। सीक्रेट सिर्फ़ एक बार दिखाया जाता है, जब कुंजी बनाई जाती है। आप कुंजी को नाम, मोड, समय-सीमा (1 से 365 दिन, या कोई नहीं) और स्कोप दे सकते हैं।

स्कोप

किसी कुंजी के स्कोप वे संगठन अनुमतियाँ हैं, जिनका वह इस्तेमाल कर सकती है। डिफ़ॉल्ट रूप से नई कुंजी को बनाने वाले की अनुमतियाँ मिलती हैं, प्रशासनिक अनुमतियों (org:manage, member:manage, sso:manage, apikey:manage, billing:manage) को छोड़कर, और कोई भी व्यक्ति किसी कुंजी को ऐसी अनुमति नहीं दे सकता जो उसके अपने पास न हो। कुंजी के स्कोप से बाहर का कॉल 403 लौटाता है, जिसमें छूटी हुई अनुमति का नाम होता है:

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

अनुमति	कुंजी क्या कर सकती है
`template:read`	टेम्पलेट, वर्ज़न और उनके PDF की सूची देखना और पढ़ना
`template:write`	टेम्पलेट बनाना, फ़ाइलें अपलोड करना, ड्राफ़्ट सहेजना, इस्तेमाल न हुए टेम्पलेट हटाना
`template:publish`	किसी ड्राफ़्ट को नए वर्ज़न के रूप में पब्लिश करना
`envelope:read`	लिफ़ाफ़ों, दस्तावेज़ों और ऑडिट ट्रेल की सूची देखना और पढ़ना; हस्ताक्षर लिंक की सूची देखना
`envelope:send`	लिफ़ाफ़े, हस्ताक्षर सेशन और हस्ताक्षर लिंक बनाना; लिंक दोबारा भेजना
`envelope:void`	प्रगति में चल रहे लिफ़ाफ़े रद्द करना
`org:manage`	वेबहुक एंडपॉइंट का प्रबंधन करना और इवेंट दोबारा डिलीवर करना; संगठन की सेटिंग्स पढ़ना
`billing:manage`	उपयोग (`GET /v1/usage`) और इनवॉइस की राशि पढ़ना

वेबहुक एंडपॉइंट के प्रबंधन के लिए org:manage चाहिए, जो कुंजियों को डिफ़ॉल्ट रूप से नहीं मिलती: एंडपॉइंट डैशबोर्ड में रजिस्टर करें, या स्पष्ट रूप से इस स्कोप वाली कुंजी बनाएँ।

कौन-सा एंडपॉइंट क्या स्वीकार करता है

API रेफ़रेंस में हर ऑपरेशन के साथ उसकी सुरक्षा स्कीम दी गई हैं। संक्षेप में:

API कुंजी या डैशबोर्ड सेशन: टेम्पलेट, लिफ़ाफ़े, हस्ताक्षर सेशन, हस्ताक्षर लिंक, वेबहुक एंडपॉइंट, संगठन की सेटिंग्स, बिलिंग का अवलोकन और उपयोग।
सिर्फ़ डैशबोर्ड सेशन: API कुंजियाँ, SCIM टोकन, SSO कनेक्शन सेटिंग्स, संगठन का लोगो अपलोड, बिलिंग चेकआउट और पोर्टल, वेबहुक सीक्रेट दिखाना।
हस्ताक्षरकर्ता टोकन: /v1/signing/*, जिसका इस्तेमाल होस्ट किया गया पेज और <bf-signing> सेशन टोकन (bfs_…) या उसके बदले मिले एक्सेस टोकन (bfa_…) के साथ करते हैं।
सार्वजनिक: /v1/links/{id} (हमेशा चालू लिंक), /v1/sso/discover, और सत्यापन API (/v1/public/*, /.well-known/bona-fide/keys.json)।

डैशबोर्ड में साइन इन करना

लोग (सर्वर नहीं) डैशबोर्ड में https://app.bonafidesign.com/sign-in पर साइन इन करते हैं। डिफ़ॉल्ट तरीका ईमेल और पासवर्ड है; विकल्प हैं: ईमेल पर भेजा गया छह अंकों का कोड (इसके बजाय मुझे कोड ईमेल करें), मैजिक लिंक, पासकी, Google या Microsoft, और आपकी कंपनी का SSO।

पासवर्ड के साथ अकाउंट बनाने पर एक ईमेल भेजा जाता है: एक कोड, जो पुष्टि करता है कि ईमेल पता आपका है। तब तक पासवर्ड से साइन इन नहीं होता। ऐसे पते से साइन अप करने पर, जिसका अकाउंट पहले से मौजूद है, कुछ नहीं बदलता और जवाब ठीक नए साइन-अप जैसा ही होता है; उस पते के मालिक को एक ईमेल मिलता है, जिसमें बताया जाता है कि इसके बजाय साइन इन कैसे करें।
पासवर्ड 12 से 128 वर्णों के होते हैं और सॉल्ट किए गए scrypt हैश के रूप में संग्रहीत होते हैं। किसी ज्ञात डेटा ब्रीच में आ चुका नया पासवर्ड अस्वीकार कर दिया जाता है: Have I Been Pwned को उसके SHA-1 हैश के सिर्फ़ पहले पाँच वर्ण भेजे जाते हैं (k-anonymity), पासवर्ड कभी नहीं। अगर वह सेवा दो सेकंड के भीतर जवाब नहीं देती, तो पासवर्ड बिना इस जाँच के स्वीकार कर लिया जाता है।
पासवर्ड भूल गए? रीसेट ईमेल में एक पेज का लिंक होता है, जहाँ आप नया पासवर्ड चुनते हैं। लिंक एक बार काम करता है और एक घंटे बाद समाप्त हो जाता है, और इसका इस्तेमाल करने पर आप हर डिवाइस से साइन आउट हो जाते हैं।
अभी तक कोई पासवर्ड नहीं? कोड, लिंक, पासकी या Google / Microsoft से बने अकाउंट उसी तरह साइन इन करते रहते हैं, और सेटिंग्स › अकाउंट में पासवर्ड जोड़ सकते हैं। पहला पासवर्ड सेट करने के लिए पिछले 15 मिनट में साइन इन किया होना ज़रूरी है (पेज आपको पुष्टि के लिए एक कोड ईमेल करता है कि यह आप ही हैं); पासवर्ड बदलने के लिए मौजूदा पासवर्ड चाहिए। दोनों ही आपके दूसरे सेशन से साइन आउट कर देते हैं।
एरर कभी अकाउंट का खुलासा नहीं करते: ग़लत पासवर्ड, अनजान पता और बिना पासवर्ड वाले अकाउंट, तीनों को एक जैसा जवाब मिलता है, और रीसेट अनुरोध पर हमेशा यही कहा जाता है कि ईमेल भेजा जा रहा है।
रेट लिमिट: पासवर्ड से साइन-इन, साइन-अप और रीसेट अनुरोध प्रति IP पता और प्रति ईमेल पता सीमित हैं; सीमा पार होने पर समय-अवधि बीतने तक जवाब 429 होता है।
कंपनी SSO: जब आपका संगठन SSO अनिवार्य करता है, तो उसके ईमेल डोमेन वाले सदस्य सिर्फ़ आइडेंटिटी प्रोवाइडर के ज़रिए साइन इन करते हैं। उनके लिए पासवर्ड, कोड और मैजिक लिंक अस्वीकार किए जाते हैं; ओनर आपात स्थिति के साइन-इन (break-glass) के लिए ईमेल कोड रख पाते हैं।

अनुरोध id

हर रिस्पॉन्स में x-request-id हेडर होता है, और हर एरर बॉडी में requestId। लॉग का मिलान करने के लिए आप अपना x-request-id (A-Z a-z 0-9 . _ - के 8 से 128 वर्ण) भेज सकते हैं; वरना API ख़ुद एक बनाता है। सपोर्ट से संपर्क करते समय इसका उल्लेख करें।