הזדהות

ה-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 שנוצרו עם המפתח הם במצב בדיקה	במצב חי

המצב נקבע לפי המפתח, אף פעם לא לפי הבקשה: ?test_mode=true ב-POST /v1/envelopes חל רק על סשנים של לוח הבקרה. רשימות (GET /v1/envelopes, GET /v1/signing-links) מחזירות רק את המצב של המפתח, והאירועים של מעטפה נשלחים רק לנקודות קצה של webhook באותו מצב. כל מעטפה וכל מטען webhook מציינים באיזה מצב הם נמצאים (testMode).

יצירה וביטול של מפתחות

המפתחות מנוהלים בלוח הבקרה, בהגדרות › מפתחות API, על ידי חברים בעלי ההרשאה apikey:manage (בעלים ומנהלים). הסוד מוצג פעם אחת, כשהמפתח נוצר. אפשר לתת למפתח שם, מצב, תפוגה (1 עד 365 ימים, או ללא) והרשאות.

Note

POST /v1/api-keys, GET /v1/api-keys ו-DELETE /v1/api-keys/{id} קיימים במדריך העזר ל-API, אבל הם מקבלים רק סשן של לוח הבקרה: מפתח API לעולם אינו יכול ליצור או לבטל מפתחות.

הרשאות (scopes)

ההרשאות של מפתח הן הרשאות הארגון שמותר לו להשתמש בהן. כברירת מחדל מפתח חדש מקבל את ההרשאות של מי שיצר אותו, פחות ההרשאות הניהוליות (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	לנהל נקודות קצה של 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. ברירת המחדל היא אימייל וסיסמה; החלופות הן קוד בן שש ספרות שנשלח באימייל (שליחת קוד באימייל במקום זאת), קישור קסם, מפתח גישה (passkey), Google או Microsoft, וה-SSO של החברה שלכם.

• יצירת חשבון עם סיסמה שולחת אימייל אחד: קוד שמאשר שהכתובת שייכת לכם. עד אז הסיסמה לא מאפשרת להיכנס. הרשמה עם כתובת שכבר יש לה חשבון לא משנה דבר ומקבלת תשובה זהה בדיוק לזו של הרשמה חדשה; בעל הכתובת מקבל אימייל שמסביר איך להיכנס במקום זאת.
• סיסמאות הן באורך 12 עד 128 תווים ונשמרות כגיבובי scrypt עם salt. סיסמה חדשה שמופיעה בדליפת נתונים ידועה נדחית: רק חמשת התווים הראשונים של גיבוב ה-SHA-1 שלה נשלחים אל Have I Been Pwned (k-anonymity), ולעולם לא הסיסמה עצמה. אם השירות לא עונה תוך שתי שניות, הסיסמה מתקבלת ללא הבדיקה.
• שכחתם את הסיסמה? אימייל האיפוס מקשר לדף שבו בוחרים סיסמה חדשה. הקישור פועל פעם אחת ותוקפו פג אחרי שעה, והשימוש בו מנתק אתכם מכל המכשירים.
• עדיין אין סיסמה? חשבונות שנוצרו עם קוד, קישור, מפתח גישה או Google / Microsoft ממשיכים להיכנס באותה דרך, ויכולים להוסיף סיסמה בהגדרות › חשבון. הגדרת הסיסמה הראשונה דורשת כניסה ב-15 הדקות האחרונות (הדף שולח לכם קוד באימייל כדי לוודא שזה אתם); שינוי שלה דורש את הסיסמה הנוכחית. בשני המקרים שאר הסשנים שלכם מנותקים.
• שגיאות לעולם אינן חושפות חשבונות: סיסמה שגויה, כתובת לא מוכרת וחשבון ללא סיסמה מקבלים את אותה תשובה, ובקשת איפוס תמיד אומרת שהאימייל בדרך.
• הגבלות קצב: בקשות כניסה עם סיסמה, הרשמה ואיפוס מוגבלות לפי כתובת IP ולפי כתובת אימייל; מעבר למגבלה התשובה היא 429 עד שחלון הזמן חולף.
• SSO של החברה: כשהארגון שלכם אוכף SSO, חברים מדומיינים של האימייל שלו נכנסים דרך ספק הזהויות בלבד. סיסמאות, קודים וקישורי קסם נדחים עבורם; הבעלים שומרים את קוד האימייל ככניסת חירום.

מזהי בקשות

כל תגובה כוללת את הכותרת x-request-id, וכל גוף שגיאה כולל requestId. אפשר לשלוח x-request-id משלכם (8 עד 128 תווים מתוך A-Z a-z 0-9 . _ -) כדי לקשר בין יומנים; אחרת ה-API יוצר מזהה. כדאי לציין אותו כשפונים לתמיכה.