توثیق

API سرورز کی توثیق تنظیم کی API کیز سے کرتا ہے۔ کلید کسی تنظیم کی ملکیت ہوتی ہے (کسی فرد کی نہیں)، اس کے ساتھ اجازتوں کا ایک مجموعہ ہوتا ہے، اور وہ بالکل ایک موڈ میں کام کرتی ہے: ٹیسٹ یا لائیو۔

کلید بھیجنا

دونوں میں سے کوئی بھی ہیڈر استعمال کریں:

# 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` واٹر مارک کے ساتھ رینڈر ہوتی ہیں	صاف
ای میل	صرف آپ کی تنظیم کے اراکین کو پہنچائی جاتی ہے	ہر وصول کنندہ کو پہنچائی جاتی ہے
بلنگ	مفت اور لامحدود، کبھی شمار نہیں ہوتی	مکمل لفافے آپ کے پلان میں شمار ہوتے ہیں
ڈیٹا	اس کلید سے بنائے گئے لفافے، لنکس اور webhook اینڈ پوائنٹس ٹیسٹ موڈ کے ہوتے ہیں	لائیو موڈ

موڈ کلید سے طے ہوتا ہے، درخواست سے کبھی نہیں: POST /v1/envelopes پر ?test_mode=true صرف ڈیش بورڈ سیشنز پر لاگو ہوتا ہے۔ فہرستیں (GET /v1/envelopes، GET /v1/signing-links) صرف کلید کے موڈ کی چیزیں واپس کرتی ہیں، اور کسی لفافے کے ایونٹس صرف اسی موڈ کے webhook اینڈ پوائنٹس پر جاتے ہیں۔ ہر لفافہ اور webhook پے لوڈ بتاتا ہے کہ وہ کس موڈ میں ہے (testMode)۔

کیز بنانا اور منسوخ کرنا

کیز کا انتظام ڈیش بورڈ میں، Settings › API keys پر، وہ اراکین کرتے ہیں جن کے پاس 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`	ٹیمپلیٹس، ورژنز اور ان کی PDFs کی فہرست دیکھے اور انہیں پڑھے
`template:write`	ٹیمپلیٹس بنائے، فائلیں اپ لوڈ کرے، مسودے محفوظ کرے، غیر استعمال شدہ ٹیمپلیٹس حذف کرے
`template:publish`	مسودے کو نئے ورژن کے طور پر شائع کرے
`envelope:read`	لفافوں، دستاویزات اور آڈٹ ٹریلز کی فہرست دیکھے اور انہیں پڑھے؛ دستخط کے لنکس کی فہرست دیکھے
`envelope:send`	لفافے، دستخط کے سیشنز اور دستخط کے لنکس بنائے؛ لنکس دوبارہ بھیجے
`envelope:void`	جاری لفافوں کو کالعدم کرے
`org:manage`	webhook اینڈ پوائنٹس کا انتظام کرے اور ایونٹس دوبارہ بھیجے؛ تنظیم کی سیٹنگز پڑھے
`billing:manage`	استعمال (`GET /v1/usage`) اور انوائس کی رقوم پڑھے

webhook اینڈ پوائنٹس کے انتظام کے لیے org:manage درکار ہے، جو کیز کو ڈیفالٹ طور پر نہیں ملتی: اینڈ پوائنٹس ڈیش بورڈ میں رجسٹر کریں، یا واضح طور پر اس اسکوپ کے ساتھ کلید بنائیں۔

کون سا اینڈ پوائنٹ کیا قبول کرتا ہے

API حوالے میں ہر آپریشن اپنی سیکیورٹی اسکیمز درج کرتا ہے۔ مختصراً:

API کلید یا ڈیش بورڈ سیشن: ٹیمپلیٹس، لفافے، دستخط کے سیشنز، دستخط کے لنکس، webhook اینڈ پوائنٹس، تنظیم کی سیٹنگز، بلنگ کا جائزہ اور استعمال۔
صرف ڈیش بورڈ سیشن: API کیز، SCIM ٹوکنز، SSO کنکشن کی سیٹنگز، تنظیم کا لوگو اپ لوڈ کرنا، بلنگ چیک آؤٹ اور پورٹل، webhook سیکرٹ ظاہر کرنا۔
دستخط کنندہ کا ٹوکن: /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 پر سائن اِن کرتے ہیں۔ ڈیفالٹ ای میل اور پاس ورڈ ہے؛ متبادل طریقے یہ ہیں: ای میل پر بھیجا گیا چھ ہندسوں کا کوڈ (Email me a code instead)، میجک لنک، پاس کی، Google یا Microsoft، اور آپ کی کمپنی کا SSO۔

پاس ورڈ کے ساتھ اکاؤنٹ بنانے پر ایک ای میل بھیجی جاتی ہے: ایک کوڈ جو تصدیق کرتا ہے کہ ایڈریس آپ کا ہے۔ تب تک پاس ورڈ سے سائن اِن نہیں ہوتا۔ ایسے ایڈریس سے سائن اپ کرنا جس کا اکاؤنٹ پہلے سے موجود ہو کچھ نہیں بدلتا اور بالکل نئے سائن اپ جیسا جواب دیتا ہے؛ ایڈریس کے مالک کو ایک ای میل ملتی ہے جس میں بتایا جاتا ہے کہ اس کے بجائے سائن اِن کیسے کریں۔
پاس ورڈز 12 سے 128 حروف کے ہوتے ہیں اور salted scrypt ہیشز کے طور پر محفوظ کیے جاتے ہیں۔ ایسا نیا پاس ورڈ مسترد کر دیا جاتا ہے جو کسی معلوم ڈیٹا بریچ میں ظاہر ہو چکا ہو: اس کے SHA-1 ہیش کے صرف پہلے پانچ حروف Have I Been Pwned کو بھیجے جاتے ہیں (k-anonymity)، پاس ورڈ کبھی نہیں۔ اگر وہ سروس دو سیکنڈ میں جواب نہ دے تو پاس ورڈ اس جانچ کے بغیر قبول کر لیا جاتا ہے۔
پاس ورڈ بھول گئے؟ ری سیٹ ای میل ایک ایسے صفحے کا لنک دیتی ہے جہاں آپ نیا پاس ورڈ منتخب کرتے ہیں۔ لنک ایک بار کام کرتا ہے اور ایک گھنٹے بعد اس کی میعاد ختم ہو جاتی ہے، اور اسے استعمال کرنے سے آپ ہر آلے پر سائن آؤٹ ہو جاتے ہیں۔
ابھی تک پاس ورڈ نہیں؟ کوڈ، لنک، پاس کی یا Google / Microsoft سے بنائے گئے اکاؤنٹس اسی طرح سائن اِن کرتے رہتے ہیں، اور Settings › Account میں پاس ورڈ شامل کر سکتے ہیں۔ پہلا پاس ورڈ مقرر کرنے کے لیے پچھلے 15 منٹ میں سائن اِن ضروری ہے (صفحہ آپ کو کوڈ ای میل کرتا ہے تاکہ تصدیق ہو کہ یہ آپ ہی ہیں)؛ اسے تبدیل کرنے کے لیے موجودہ پاس ورڈ درکار ہے۔ دونوں صورتوں میں آپ کے دوسرے سیشنز سائن آؤٹ ہو جاتے ہیں۔
ایررز کبھی اکاؤنٹس ظاہر نہیں کرتے: غلط پاس ورڈ، نامعلوم ایڈریس اور بغیر پاس ورڈ والے اکاؤنٹ کو ایک ہی جواب ملتا ہے، اور ری سیٹ کی درخواست ہمیشہ یہی کہتی ہے کہ ای میل بھیجی جا رہی ہے۔
ریٹ لمٹس: پاس ورڈ سے سائن اِن، سائن اپ اور ری سیٹ کی درخواستیں فی IP ایڈریس اور فی ای میل ایڈریس محدود ہیں؛ حد سے تجاوز پر وقفہ گزرنے تک جواب 429 ہوتا ہے۔
کمپنی کا SSO: جب آپ کی تنظیم SSO لازمی کرتی ہے، تو اس کے ای میل ڈومینز والے اراکین صرف شناختی فراہم کنندہ کے ذریعے سائن اِن کرتے ہیں۔ ان کے لیے پاس ورڈز، کوڈز اور میجک لنکس مسترد ہوتے ہیں؛ مالکان ہنگامی سائن اِن کے طور پر ای میل کوڈ برقرار رکھتے ہیں۔

درخواست کی ids

ہر جواب میں x-request-id ہیڈر ہوتا ہے، اور ہر ایرر باڈی میں requestId۔ لاگز کو آپس میں ملانے کے لیے آپ اپنی x-request-id (A-Z a-z 0-9 . _ - کے 8 سے 128 حروف) بھیج سکتے ہیں؛ ورنہ API خود ایک بنا دیتا ہے۔ سپورٹ سے رابطہ کرتے وقت اس کا حوالہ دیں۔