אימות באמצעות ממשק ה-API Notiondesk באמצעות מפתחות API

כל בקשת API של Notiondesk מאומתת באמצעות אסימון נושא: מפתח API של סביבת עבודה, או אסימון גישה של OAuth עבור אפליקציות הפועלות מטעם לקוחות Notiondesk אחרים. מאמר זה מראה כיצד ליצור מפתח API של Notiondesk, לבחור את ההיקפים שלו, לשלוח אותו עם הבקשות שלך, ולסובב או לבטל אותו.

השתמשו במפתח API לאוטומציה שאתם מפעילים עבור סביבת העבודה שלכם: סקריפט, משימה מתוזמנת, שלב CI או כלי פנימי. אם אתם בונים אפליקציה שאליה מתחברים לקוחות Notiondesk אחרים, השתמשו ב-OAuth במקום זאת.

לפני שאתם מתחילים

• סביבת העבודה שלך נמצאת בתוכנית Enterprise.

• אתה בעל סביבת העבודה או מנהל מערכת.

צור מפתח API Notiondesk

1. בלוח המחוונים Notiondesk שלך, לחץ על הגדרות .

2. תחת סביבת עבודה , פתח את מפתחים , לאחר מכן את מפתחות API .

3. לחץ על צור מפתח .

4. הזן תווית המציינת למה מיועד המפתח, לדוגמה CI automation או Redirect import.

5. תחת טווחים , בחר רק את הטווחים הדרושים לשילוב. ראה בחירת הטווחים הנכונים .

6. בחר תפוגה : 30 יום , 90 יום , שנה אחת או ללא תפוגה .

7. לחץ על צור .

8. לחץ על העתק מפתח ואחסן את המפתח במשתני הסביבה או במנהל הסודות שלך.

9. לחץ על שמרתי את המפתח .

המפתח מוצג פעם אחת בלבד. אם תאבד אותו, סובב את המפתח כדי לקבל סוד חדש.

הערה: אם האפשרות "צור מפתח " מציגה מנעול ואת הסבר הכלי "זמין בתוכניות עם גישת API", התוכנית שלך אינה כוללת את ה-API. לחיצה עליו פותחת את אפשרויות השדרוג.

בחרו את הטווחים הנכונים

סקופ הוא הרשאה המצורפת למפתח. כל נתיב API Notiondesk דורש סקופ אחד, ומפתח יכול להכיל כמה.

תן לכל אינטגרציה את קבוצת ההיקפים הקטנה ביותר שהיא צריכה:

כיצד תפקידי סביבת עבודה מגבילים מפתח

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

אם תפקיד היוצר משתנה, גם הטווח האפקטיבי של המפתח משתנה איתו. אם היוצר עוזב את סביבת העבודה, המפתח מפסיק לפעול. נהל תפקידים ב כיצד להזמין חבר צוות .

שלח את המפתח עם כל בקשה

שלח את המפתח בכותרת Authorization עם הסכימה Bearer:

קובץ 200 OK עם רשימה של מרכזי העזרה שלך מאשר שהמפתח פועל. מפתח אחד פועל עבור כל מרכז עזרה בסביבת העבודה שלו.

אותה בקשה ב-JavaScript:

ובפיתון:

שמור את מפתח ה-API Notiondesk שלך בטוח

curl "<https://api.notiondesk.so/sites>" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

const response = await fetch("<https://api.notiondesk.so/sites>", {
  headers: {
    Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
    "nd-version": "2026-10-16",
  },
});

const sites = await response.json();

import os
import requests

response = requests.get(
    "<https://api.notiondesk.so/sites>",
    headers={
        "Authorization": f"Bearer {os.environ['NOTIONDESK_API_KEY']}",
        "nd-version": "2026-10-16",
    },
)
sites = response.json()

• שמור את המפתחות בשרת שלך. לעולם אל תשים מפתח בקוד דפדפן, אפליקציה לנייד או מאגר נתונים ציבורי.

• אחסן מפתחות במשתני סביבה או במנהל סודות, לא בקוד המקור.

• צור מפתח אחד לכל אינטגרציה, עם תווית משלו, כך שתוכל לבטל אחד מבלי לשבור את האחרים.

• בחר תאריך תפוגה עבור מפתחות המשמשים סקריפטים זמניים.

• סובב מפתח כאשר מישהו שידע זאת עוזב את הצוות שלך.

• סמן את העמודה "לאחרונה בשימוש" ובטל מפתחות שאף אחד לא משתמש בהם.

סיבוב או ביטול מפתח

פתחו את הגדרות > מפתחים > מפתחות API והשתמשו בתפריט בסוף שורת המפתח.

סיבוב מחליף את הסוד. אשר באמצעות סיבוב : הסוד הנוכחי מפסיק לפעול באופן מיידי והסוד החדש מוצג פעם אחת. עדכן את האינטגרציה שלך באופן מיידי. לא ניתן לסובב מפתח שפג תוקפו; צור מפתח חלופי במקום זאת.

ביטול משבית את המפתח לתמיד. אישור באמצעות ביטול : אוטומציות המשתמשות במפתח מפסיקות לפעול באופן מיידי, ולא ניתן לבטל זאת.

פתרון בעיות אימות

WWW-Authenticate: Bearer error="insufficient_scope", scope="sync"

שאלות נפוצות

מה הלאה

• התחל עם ממשק ה-API של REST Notiondesk

• חבר את האפליקציה שלך ל-Notiondesk באמצעות OAuth

• טיפול בשגיאות API, מגבלות קצב וניסיונות חוזרים של Notiondesk