מפתחות API

כל קריאה ל־REST API של Joryio מאומתת באמצעות מפתח API. מפתחות משויכים לסביבת עבודה אחת, נושאים רשימת הרשאות מפורשת וניתן להגביל אותם לרשימת כתובות IP.

כל נקודות הקצה בעמוד זה יחסיות לכתובת הבסיס: https://api-eu1.joryio.com - ראו סקירת API.

יצירת מפתח

פתחו את לוח הבקרה של Joryio ועברו אל Settings → API Keys.
לחצו Create API Key.
תנו למפתח שם ו(אופציונלי) תיאור שחברי הצוות יראו.
הוסיפו, לפי הצורך, IP allowlist - רשימת טווחי CIDR או כתובות IP שמופרדים בפסיקים או ברווחים. השאירו את השדה ריק כדי לאפשר גישה מכל כתובת IP.
סמנו את ההרשאות שהמפתח צריך. בחרו את הסט הקטן ביותר שעובד - ראו את קטלוג ההרשאות למטה.
לחצו Create key.

הצגה חד־פעמית

הערך המלא של המפתח מוצג פעם אחת בלבד, מיד לאחר היצירה, ולעולם לא שוב. העתיקו אותו למנהל הסודות שלכם (1Password, Vault, AWS Secrets Manager וכו') לפני סגירת החלון. אם איבדתם אותו, מחקו את המפתח וצרו חדש - Joryio לא יכולה לשחזר את המקורי.

הפורמט של המפתח הוא jry_live_<random> למפתחות בסביבת ייצור ו־jry_test_<random> למפתחות בדיקה. ה־prefix הגלוי של המפתח (jry_live_abc123) מוצג ברשימת המפתחות בלוח הבקרה וביומני השרת, כך שתוכלו לזהות איזה מפתח ביצע כל פעולה בלי לחשוף את הערך המלא.

שימוש במפתח

שלחו את המפתח כטוקן Bearer בכותרת Authorization בכל בקשה:

GET /users/by-user-id/user_123
Host: api-eu1.joryio.com
Authorization: Bearer jry_live_98f31a72…
Content-Type: application/json

קטלוג הרשאות

הרשאות נכתבות בפורמט <resource>:<verb>. אלה הפעלים שבשימוש:

פועל	משמעות	דוגמה
`read`	הצגת רשימה או שליפת רשומות קיימות	`users:read`, `campaigns:read`
`write`	יצירה או עדכון רשומות	`users:write`, `segments:write`
`send`	הפעלת שליחה	`campaigns:send`
`delete`	מחיקה לצמיתות של רשומות	`users:delete`, `campaigns:delete`
`track`	שליחת אירועי אנליטיקה	`events:track`
`activate`	הפעלה, השהיה או חידוש של תהליך עבודה פעיל	`canvas:activate`
`alias`	חיבור/ניתוק מזהים חלופיים	`users:alias`
`merge`	מיזוג שני פרופילי משתמש	`users:merge`
`export`	ייצוא רשומות בכמות גדולה	`users:export`

למטה הקטלוג הציבורי המלא - הוא מוחזר גם על ידי GET /api-keys/permissions:

Events (אירועים)

הרשאה	מה היא מאפשרת
`events:track`	שליחת אירועים מותאמים מהשרתים שלכם או מה־SDK.
`events:read`	שאילתה על אירועים שנרשמו.

Users (משתמשים)

הרשאה	מה היא מאפשרת
`users:read`	חיפוש פרופילי משתמשים ומאפיינים לפי ID.
`users:write`	יצירה או עדכון של מאפייני משתמש.
`users:delete`	הסרה לצמיתות של פרופילי משתמשים (GDPR / זכות למחיקה).
`users:alias`	חיבור או ניתוק של מזהים חיצוניים וכינויי אימייל למשתמש.
`users:merge`	מיזוג של שני פרופילי משתמש לאחד.
`users:export`	ייצוא בכמות גדולה של פרופילי משתמשים לניתוח חיצוני.

Campaigns (קמפיינים)

הרשאה	מה היא מאפשרת
`campaigns:read`	הצגת קמפיינים וצפייה בתצורה שלהם.
`campaigns:write`	יצירה או עריכה של טיוטות קמפיין דרך ה־API.
`campaigns:send`	הפעלת שליחת קמפיין למשתמש או סגמנט ספציפי.
`campaigns:delete`	הסרה לצמיתות של קמפיינים מסביבת העבודה.

Segments (סגמנטים)

הרשאה	מה היא מאפשרת
`segments:read`	הצגת סגמנטים וצפייה במספר החברים בהם.
`segments:write`	יצירה או עדכון של הגדרות סגמנט.
`segments:delete`	מחיקה לצמיתות של סגמנטים והיסטוריה.

User Journeys (מסעות לקוח)

הרשאה	מה היא מאפשרת
`canvas:read`	רשימת מסעות לקוח ובדיקת גרף השלבים.
`canvas:write`	יצירה או עריכה של טיוטות מסע לקוח.
`canvas:activate`	התחלה, השהיה או חידוש של מסע לקוח פעיל.
`canvas:delete`	הסרה של מסעות לקוח והיסטוריה.

Templates (תבניות)

הרשאה	מה היא מאפשרת
`templates:read`	שליפת תוכן תבניות אימייל, SMS ו־push.
`templates:write`	יצירה או עריכה של תבניות הודעות לשימוש חוזר.
`templates:delete`	מחיקה לצמיתות של תבניות מ־Brand Studio.

Subscriptions (הרשמות)

הרשאה	מה היא מאפשרת
`subscriptions:read`	צפייה במצב ה־opt-in של משתמש בערוצים שונים.
`subscriptions:write`	רישום או ביטול רישום משתמשים לקבוצות וערוצים.

Apps & SDK Keys (אפליקציות ומפתחות SDK)

הרשאה	מה היא מאפשרת
`apps:read`	הצגת האפליקציות ומפתחות ה־SDK הרשומים בסביבת העבודה.
`apps:write`	הוספה, החלפה או הסרה של מפתחות SDK לאפליקציות מובייל ו־Web.

Asset Library (ספריית נכסים)

הרשאה	מה היא מאפשרת
`assets:read`	שליפת תמונות, פונטים ומדיה משותפת.
`assets:write`	העלאה, שינוי שם או מחיקה של קבצים בספריית הנכסים.

Entities (ישויות)

הרשאה	מה היא מאפשרת
`entities:read`	שאילתה על רשומות ישות (מוצרים, מאמרים, מקומות…).
`entities:write`	יצירה או עדכון של רשומות ומאפייני ישות.

Analytics (אנליטיקה)

הרשאה	מה היא מאפשרת
`analytics:read`	שליפת מדדים מצטברים, משפכים ונתוני דוחות.

Deliverability (יכולת מסירה)

הרשאה	מה היא מאפשרת
`email_suppression:read`	בדיקת רשימת החסימה באימייל (החזרות, תלונות והוספות ידניות).
`email_suppression:write`	הוספת רשומות לרשימת החסימה באימייל או הסרתן.
`sms_suppression:read`	בדיקת רשימת חסימת ה־SMS (תגובות STOP, כשלים).
`sms_suppression:write`	הוספה או הסרה של מספרי טלפון מרשימת חסימת ה־SMS.

Frequency Caps (מגבלות תדירות)

הרשאה	מה היא מאפשרת
`touching_rules:read`	בדיקת כללי הגבלת התדירות והספירות הנוכחיות שלהם.
`touching_rules:write`	יצירה, עריכה או הסרה של כללי הגבלת תדירות.

WhatsApp (וואטסאפ)

הרשאה	מה היא מאפשרת
`whatsapp:read`	קריאת התצורה של חשבון WhatsApp Business.
`whatsapp:write`	עדכון התצורה של חשבון WhatsApp Business.

AI Agents (סוכני AI)

הרשאה	מה היא מאפשרת
`ai_agents:read`	הצגת סוכני AI והתצורה שלהם.
`ai_agents:write`	יצירה או עריכה של סוכני AI והגדרות הספקים שלהם.

רשימת כתובות IP מורשות

ניתן להצמיד מפתח לרשימה קבועה של כתובות IP מקור. כשהרשימה ריקה, בקשות מכל IP מתקבלות (ברירת המחדל). כשיש לה ערכים, רק בקשות שכתובת המקור שלהן תואמת לפחות לרשומה אחת מתקבלות.

תחביר נתמך

כתובת IPv4 רגילה - 203.0.113.42
טווח CIDR של IPv4 - 10.0.0.0/24, 192.168.1.0/16
כתובת IPv6 - התאמה מדויקת בלבד (אין CIDR ל־IPv6 בשלב זה)

אפשר לשלב כמה ערכים באמצעות הפרדה בפסיקים בלוח הבקרה:

10.0.0.0/24, 203.0.113.42, 2001:db8::1

זיהוי כתובת המקור

כתובת הלקוח נפתרת מהכותרת המהימנה של רשת הקצה (שנכתבת מחדש בכל בקשה בקצה - ערך שנשלח על ידי הלקוח אינו נשמר), ואם היא חסרה נעשה שימוש בכתובת החיבור של שרת ה־proxy המהימן. הערך השמאלי ביותר של X-Forwarded-For, שבשליטת הלקוח, אינו בשימוש בכוונה - כך שאי אפשר לזייף את רשימת ה־IP. כתובות IPv6 שממופות מ־IPv4 (::ffff:203.0.113.42) מנורמלות לצורת ה־IPv4 שלהן לפני ההשוואה.

צורת תגובת דחייה

כשבקשה מגיעה מ־IP שלא ברשימה המותרת, ה־API מחזיר 401 Unauthorized עם:

{
  "statusCode": 401,
  "message": "Request IP is not allowed for this API key",
  "timestamp": "2026-05-12T08:14:00.000Z",
  "path": "/users"
}

הדחייה מתועדת בצד השרת עם ה־prefix של המפתח וכתובת ה־IP שנדחתה, כדי שתוכלו לערוך ביקורת.

נקודות קצה לניהול מפתחות

מפתחות מנוהלים דרך לוח הבקרה (Settings → API Keys) או דרך ה־API:

שיטה	Endpoint	תיאור
GET	`/api-keys/permissions`	רשימת כל ההרשאות הניתנות להענקה
POST	`/api-keys`	יצירת מפתח (`?environment=live` או `test`; גוף: `name`, `description?`, `permissions[]`, `ipAllowlist?`, `expiresAt?`) - הערך המלא מוחזר פעם אחת
GET	`/api-keys`	הצגת המפתחות בסביבת העבודה
GET	`/api-keys/:apiKeyId`	קבלת המטא־נתונים של מפתח
PUT	`/api-keys/:apiKeyId`	עדכון שם, תיאור, הרשאות, רשימת IP או תפוגה
POST	`/api-keys/:apiKeyId/revoke`	השבתת מפתח (מפסיק לאמת מיידית)
POST	`/api-keys/:apiKeyId/rotate`	יצירת ערך מפתח חדש עם אותן הרשאות - הערך החדש מוחזר פעם אחת
DELETE	`/api-keys/:apiKeyId`	מחיקת מפתח לצמיתות (מחזיר `204`)

קורא לעולם לא יכול להעניק למפתח הרשאות שאין לו בעצמו.

שדות תגובת רשימה

GET /api-keys מחזיר { "apiKeys": [...] }; לכל מפתח יש את המבנה הבא (הערך המלא של המפתח והגיבוב שלו לעולם אינם נחשפים):

{
  "apiKeys": [
    {
      "id": "7c2e4f6a-1b3d-4e5f-8a9b-0c1d2e3f4a5b",
      "name": "ServerSide Updates",
      "description": "Used by our backend to send events.",
      "keyPrefix": "jry_live_98f31a72",
      "permissions": ["events:track", "users:write"],
      "lastUsedAt": "2026-05-12T08:14:00.000Z",
      "expiresAt": null,
      "isActive": true,
      "createdAt": "2026-02-19T12:00:00.000Z",
      "updatedAt": "2026-02-19T12:00:00.000Z"
    }
  ]
}

ה-ipAllowlist של המפתח נקבע ביצירה/עדכון; הוא נאכף על כל בקשה אך אינו נכלל בתגובת הרשימה.

שגיאות נפוצות

סטטוס	הודעה	מה לבדוק
`401`	`Invalid API key format`	הכותרת חסרה, פגומה או אינה מתחילה ב־`jry_`.
`401`	`Invalid or expired API key`	המפתח בוטל, נמחק או ש־`expiresAt` שלו חלף.
`401`	`Request IP is not allowed for this API key`	כתובת המקור לא תאמה לאף ערך - ראו רשימת כתובות IP מורשות.
`403`	`This API key does not have the required permissions: ...`	המפתח תקין, אך אין לו את ההרשאה שנדרשת לנקודת הקצה.
`403`	`ORG_HARD_SUSPENDED: organization is suspended. Read-only access only.`	הארגון הבעלים הושעה - פנו לתמיכה.

החלפת מפתח

קראו ל־POST /api-keys/:apiKeyId/rotate (או השתמשו בלוח הבקרה): המפתח מקבל ערך סודי חדש ו־keyPrefix חדש, המוחזרים פעם אחת בלבד בתגובה, תוך שמירה על השם, ההרשאות וה־ID. כל מערכת שעדיין משתמשת בערך הישן תתחיל להיכשל מיד, לכן הפיצו תחילה את הערך החדש בכל מקום אפשרי והשתמשו ב־keyPrefix ביומני הגישה כדי לאתר אינטגרציות שעדיין משתמשות במפתח הישן. להחלפה ללא השבתה, צרו מפתח שני בעל אותן הרשאות, העבירו אליו את המערכות הקוראות ולאחר מכן מחקו את המפתח הישן.

יצירת מפתח​

שימוש במפתח​

קטלוג הרשאות​

Events (אירועים)​

Users (משתמשים)​

Campaigns (קמפיינים)​

Segments (סגמנטים)​

User Journeys (מסעות לקוח)​

Templates (תבניות)​

Subscriptions (הרשמות)​

Apps & SDK Keys (אפליקציות ומפתחות SDK)​

Asset Library (ספריית נכסים)​

Entities (ישויות)​

Analytics (אנליטיקה)​

Deliverability (יכולת מסירה)​

Frequency Caps (מגבלות תדירות)​

WhatsApp (וואטסאפ)​

AI Agents (סוכני AI)​

רשימת כתובות IP מורשות​

תחביר נתמך​

זיהוי כתובת המקור​

צורת תגובת דחייה​

נקודות קצה לניהול מפתחות​

שדות תגובת רשימה​

שגיאות נפוצות​

החלפת מפתח​