অথেন্টিকেশন

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 নিজেই একটি তৈরি করে। সাপোর্টের সঙ্গে যোগাযোগ করার সময় এটি উল্লেখ করুন।