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

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

מתי להשתמש ב-OAuth במקום מפתח API

כל נתיב API Notiondesk מקבל את שני הפרטים ועונה עליהם באותו אופן: אותם היקפים, תגובות ושגיאות.

מה האפליקציה שלך צריכה לדעת

קרא את נקודות הקצה ממסמך המטה-דאטה של ​​שרת ההרשאה במקום לקודד אותן בקידוד קשיח.

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

שלב 1: רישום האפליקציה שלך

הירשם פעם אחת עם רישום לקוחות דינמי :

התגובה 201 Created מכילה את ה-client_id שלך, ומכיוון שביקשת client_secret_post, גם client_secret. הסוד מוצג פעם אחת: אחסן אותו עם סודות השרת האחרים שלך.

עם "token_endpoint_auth_method": "none", האפליקציה שלך היא לקוח ציבורי ללא סוד, ו-PKCE מגן על חילופי הקוד שלה.

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

כללי URI להפניה מחדש

curl -X POST "https://api.notiondesk.so/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Acme Reports", "redirect_uris": ["https://acme.example/oauth/callback"], "token_endpoint_auth_method": "client_secret_post"}'

• השתמש ב-https, או http על מארח לולאה חוזרת: 127.0.0.1, localhost או [::1].

• הפניה חוזרת (loopback redirect) תואמת בכל פורט. כל הפניה אחרת חייבת להתאים במדויק.

• תווים כלליים, מקטעים, אישורים לפני המארח (user@), קו נטוי הפוך, תווים שאינם ASCII ומארחים מקודדים באחוזים נדחים.

• המארח שהלקוח רואה במסך ההסכמה מגיע מכתובות ה-URI להפניה שלך או מכתובת ה-URL client_id שלך. רשום רק מארחים שבבעלותך.

שלב 2: שלח את הלקוח אל Notiondesk

צור code_verifier אקראי, לאחר מכן גזור את code_challenge כ-hash SHA-256 של המאמת, מקודד ב-base64url ( PKCE ). הפנה את דפדפן הלקוח אל:

https://api.notiondesk.so/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Fcallback
  &scope=read%20write
  &state=RANDOM_STATE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.notiondesk.so

• resource נדרש וחייב להיות בדיוק https://api.notiondesk.so: אותיות קטנות, ללא נטוי, ללא נתיב. ערך חסר או שונה עונה על invalid_request.

• scope היא רשימה מופרדת ברווחים. בקש רק את ההיקפים שבהם האפליקציה שלך משתמשת.

• state מגן מפני זיוף בקשות בין אתרים. בדוק זאת כאשר הלקוח חוזר.

אסימון שהונפק עבור Notiondesk REST API פועל רק עם REST API. אסימון שהונפק עבור Workspace MCP נדחה על ידי REST API, ולהיפך.

שלב 3: הלקוח מאשר את האפליקציה שלך

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

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

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

הלקוח אינו יכול לאשר את הבקשה כאשר:

• התפקיד שלהם לא מאפשר אף אחד מההיקפים שביקשת;

• לסביבת העבודה שלהם אין גישת API. מסך ההסכמה מראה לאחר מכן "תוכנית סביבת העבודה אינה כוללת גישת API". גישת API דורשת תוכנית Enterprise.

לאחר האישור, הדפדפן חוזר ל-redirect_uri שלך עם code, state שלך, ו-iss, המזהה של שרת ההרשאה Notiondesk. אם הלקוח מסרב, ההפניה תישא את error=access_denied במקום זאת.

שלב 4: החלפת הקוד בטוקנים

הקוד תקף למשך 60 שניות ופועל פעם אחת:

השמט את client_secret עבור לקוח ציבורי. התגובה:

scope מפרט את הטוקים שהלקוח העניק, שיכולים להיות פחות ממה שביקשת. אחסן את שני האסימונים בשרת שלך.

שלב 5: קריאה ל-Notiondesk API

שלח את אסימון הגישה כאסימון נושא, בדיוק כמו מפתח API:

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

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

שלב 6: רענון אסימון הגישה

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

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

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=THE_CODE \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d redirect_uri=https://acme.example/oauth/callback

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8f3c...",
  "scope": "read write"
}

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

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d refresh_token=THE_REFRESH_TOKEN

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

כיצד לקוחות מבטלים את האפליקציה שלך

בעלי סביבות עבודה ומנהלים רואים כל אפליקציה עם גישה לסביבת העבודה שלהם תחת הגדרות > מפתחים > אפליקציות מחוברות . אפליקציות המשתמשות ב-REST API מציגות את REST API בעמודה Access , יחד עם האפליקציה, האדם שאישר אותה, היקפיה והפעילות האחרונה שלה. ביטול מסיים את ההענקה באופן מיידי: אסימון הגישה ואסימון הרענון שלה מפסיקים לפעול בבקשה הבאה.

מענק מסתיים גם מעצמו:

• לאחר 30 יום ללא רענון;

• כאשר אסימון הרענון שלו נעשה בו שימוש חוזר.

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

פתרון בעיות Notiondesk OAuth

נקודות הקצה של ההרשאה והטוקן עונות על שגיאות OAuth סטנדרטיות, ולא על מעטפת השגיאה של ה-API Notiondesk:

{"error": "invalid_grant", "error_description": "Invalid authorization code."}

נקודת הקצה של ההרשאה מציגה את השגיאות הללו בעצמה ולעולם לא מפנה בקשה לא חוקית אל redirect_uri שלך. הסכמה שנדחתה מגיעה לאפליקציה שלך רק כהפניה error=access_denied.

קריאות ל-API עצמו עונות על מעטפת השגיאה Notiondesk של ה-API . אסימון גישה שפג תוקפו או בוטל עונה על 401 authentication_error עם ההודעה "מפתח API לא חוקי או חסר.", אותה הודעה שמקבל מפתח API שאינו שמיש.

שאלות נפוצות

מה הלאה

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

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

• ניתוק או ביטול גישת Workspace MCP