אפליקציות OAuth

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

יישומי מפתחים זמינים ב-Nodaro Cloud ובהתקנות של מהדורת Business.

OAuth או אסימון API אישי

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

השתמשו ב-OAuth במקרים האלה:

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

איך הזרימה עובדת

1. המשתמש לוחץ על חיבור ל-Nodaro באתר שלכם.
2. האתר שלכם מפנה את הדפדפן לדף /oauth/authorize של Nodaro, עם ה-client_id, ה-redirect_uri, ה-scope וה-state שלכם.
3. Nodaro מציג את מסך ההסכמה, אחרי התחברות אם צריך. המסך מציג את השם, הלוגו וההרשאות המבוקשות של האפליקציה שלכם, ואת החשבון שייתן את הגישה. הכפתור שימוש בחשבון אחר מנתק את המשתמש מהחשבון וחוזר לאותו מסך.
4. המשתמש לוחץ על אישור, ו-Nodaro יוצר authorization code חד־פעמי.
5. הדפדפן חוזר ל-redirect_uri שלכם עם ?code=...&state=....
6. השרת שלכם מחליף את הקוד באסימון גישה ב-POST /v1/oauth/token, עם ה-client_id וה-client_secret שלכם.
7. השרת שלכם קורא ל-API של Nodaro בשם המשתמש, עם Authorization: Bearer ndr_app_....

רישום האפליקציה שלכם

ניהול האפליקציה

• החליפו את הסוד בדף של האפליקציה כשאתם מאבדים אותו, או כנוהל אבטחה שגרתי. הסוד הישן מפסיק לעבוד מיד, ולכן עדכנו מיד את התצורה של כל שירות שרץ.
• מחקו את האפליקציה כדי לבטל כל אסימון גישה שניתן לה. משתמשים שאישרו אותה יצטרכו לחבר אותה שוב.
• חמש אפליקציות לכל משתמש. לקוחות MCP שרשמו את עצמם מופיעים באותה רשימה, אבל לא נספרים במגבלה.
• מקוד, המשאב client.developerApps של ה-SDK יוצר, מעדכן ומוחק אפליקציות ומחליף את הסודות שלהן. ראו את הדף SDK ל-TypeScript.

הרשאות

כל הרשאה (scope) היא היתר אחד שהאפליקציה שלכם מבקשת. בקשו רק את ההרשאות שאתם משתמשים בהן: המשתמשים רואים כל הרשאה מבוקשת במסך ההסכמה, ורשימה קצרה זוכה באמון שלהם.

• חלק מההרשאות שולטות בגישה לנתיבי REST, חלק בכלי ה-MCP, וחלק בשניהם. שרת ה-MCP מסתיר כל כלי שההרשאה שלו חסרה באסימון.
• אסימון בלי ההרשאה שנתיב דורש נדחה עם 403 insufficient_scope, וההרשאה החסרה מופיעה ב-missingScope. ראו את הסעיף שגיאות.
• הרשאות סביבת העבודה אף פעם לא מתווספות לאסימון שהונפק לפני שהיו ארגונים. כדי לתת אותן, המשתמש צריך לאשר שוב את האפליקציה שלכם.
• הרצה של אפליקציה שפורסמה דורשת workflows:execute כדי להתחיל את ההרצה ו-jobs:read כדי לקרוא את ההתקדמות שלה. קריאת הרצות אפליקציה מתאפשרת גם עם assets:read או workflows:execute, ולכן אפליקציה שמתחילה הרצות תמיד יכולה לבדוק את הסטטוס שלהן.
• טעינה של אפליקציה שפורסמה עם GET /v1/app/:slug לא דורשת הרשאה.
• ההרשאות חלות רק על אסימונים של אפליקציות OAuth. Nodaro לא בודק הרשאות באסימוני סשן ובאסימוני API אישיים.

ניהול אפליקציות שפורסמו

עם אסימון של אפליקציית OAuth, נתיבי /v1/apps/* ונתיבי המונטיזציה האלה בודקים הרשאה:

קטלוג השוק, GET /v1/apps/browse ו-GET /v1/apps/by-slug/:slug/latest-version, לא דורש הרשאה. אסימון בלי ההרשאה נדחה עם 403 insufficient_scope עם missingScope.

הפניית המשתמש למסך ההסכמה

כשהמשתמש לוחץ על חיבור ל-Nodaro, הפנו את הדפדפן לכתובת הזאת:

https://nodaro.example.com/oauth/authorize?
  client_id=app_...&
  redirect_uri=https://yourapp.com/oauth/callback&
  response_type=code&
  scope=workflows:read+workflows:execute&
  state=<random CSRF token>

צרו את state בשרת שלכם:

import { randomBytes } from "node:crypto"

// In your /connect handler:
const state = randomBytes(32).toString("hex")
req.session.oauthState = state

const url = new URL("https://nodaro.example.com/oauth/authorize")
url.searchParams.set("client_id", process.env.NODARO_CLIENT_ID!)
url.searchParams.set("redirect_uri", "https://yourapp.com/oauth/callback")
url.searchParams.set("response_type", "code")
url.searchParams.set("scope", "workflows:read workflows:execute")
url.searchParams.set("state", state)
res.redirect(url.toString())

• אם המשתמש לוחץ על ביטול, Nodaro מפנה ל-redirect_uri שלכם עם error=access_denied, עם error_description ועם ה-state שלכם. התייחסו לביטול כאל תוצאה רגילה, לא כאל תקלה.
• אם כתובת ההפניה לא רשומה, מסך ההסכמה מציג דף שגיאה ולא מפנה לשום מקום, גם בלחיצה על ביטול וגם בלחיצה על אישור.

החלפת הקוד באסימון

אחרי שהמשתמש לוחץ על אישור, Nodaro מפנה את הדפדפן לכתובת הקריאה החוזרת שלכם:

https://yourapp.com/oauth/callback?code=ndr_code_...&state=<your state>

1. בדקו קודם את state. אם הוא לא תואם לערך שבסשן של המשתמש, עצרו: זו ההגנה מפני זיוף בקשות בין אתרים.
2. החליפו את הקוד בשרת שלכם. לעולם אל תבצעו את הקריאה הזאת מדפדפן, שבו כל מי שיש לו כלי מפתחים יכול לקרוא את ה-client_secret שלכם.

import { createClient, StaticTokenAuth } from "@nodaro/sdk"

// The token endpoint is public: your client ID and secret authenticate
// the request, so the client needs no token of its own.
const client = createClient({
  baseUrl: "https://nodaro.example.com",
  auth: new StaticTokenAuth(""),
})

const tokens = await client.oauth.exchangeCode({
  client_id: process.env.NODARO_CLIENT_ID!,
  client_secret: process.env.NODARO_CLIENT_SECRET!,
  code: req.query.code as string,
  redirect_uri: "https://yourapp.com/oauth/callback",
})
// tokens.access_token: "ndr_app_..."
// tokens.scope:        the scopes the user granted, separated by spaces
// tokens.expires_in:   7776000 (seconds, that is 90 days)
// tokens.token_type:   "Bearer"

curl -X POST https://nodaro.example.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "app_...",
    "client_secret": "sec_...",
    "code": "ndr_code_...",
    "redirect_uri": "https://yourapp.com/oauth/callback"
  }'

התגובה משתמשת בשמות השדות הסטנדרטיים של OAuth:

{
  "access_token": "ndr_app_...",
  "token_type": "Bearer",
  "scope": "workflows:read workflows:execute",
  "expires_in": 7776000
}

• קוד עובד פעם אחת. החלפה שנייה של אותו קוד נדחית עם 400 invalid_grant.
• תוקף הקוד פג 10 דקות אחרי שהוא הונפק. החליפו אותו ברגע שהוא מגיע לכתובת הקריאה החוזרת שלכם.
• נקודת הקצה של האסימונים מקבלת גוף בקשה ב-JSON ובקידוד של טופס. לקוחות OAuth סטנדרטיים ששולחים application/x-www-form-urlencoded עובדים בלי שינוי, בשיטה client_secret_post.

לקוחות ציבוריים: PKCE

אפליקציות מובייל, אפליקציות של דף יחיד וכלי CLI לא יכולים לשמור client_secret. במקום זה הם משתמשים ב-PKCE. Nodaro תומך רק בשיטה S256; השיטה plain נדחית עם 400 invalid_request.

https://nodaro.example.com/oauth/authorize?
  client_id=app_...&
  redirect_uri=https://yourapp.com/oauth/callback&
  response_type=code&
  scope=workflows:read+workflows:execute&
  state=<random CSRF token>&
  code_challenge=<base64url SHA-256 of the verifier>&
  code_challenge_method=S256

curl -X POST https://nodaro.example.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "app_...",
    "code": "ndr_code_...",
    "redirect_uri": "https://yourapp.com/oauth/callback",
    "code_verifier": "<the original verifier>"
  }'

לקוח שיכול לשמור סוד רשאי לשלוח גם סוד וגם verifier של PKCE. Nodaro בודק כל אחד מהם שנשלח.

קריאה ל-API עם האסימון

צרו לקוח אחד לכל משתמש, עם אסימון הגישה של אותו משתמש:

import { createClient, StaticTokenAuth } from "@nodaro/sdk"

const userClient = createClient({
  baseUrl: "https://nodaro.example.com",
  auth: new StaticTokenAuth(tokens.access_token),
})

// Every call acts as the user who authorized your app, within the granted scopes.
const projects = await userClient.projects.list()
const workflows = await userClient.workflows.list(projects.data[0].id)
const run = await userClient.workflows.run(workflows.data[0].id)

בלי ה-SDK, שלחו את האסימון בכותרת Authorization: Bearer של כל קריאת REST. נקודות הקצה מפורטות במדריך של ה-REST API.

כשתוקף האסימון פג

אסימון גישה תקף 90 ימים. Nodaro לא מנפיק אסימוני רענון: יש סוג אסימון אחד, מקום אחד לשמור אותו וכלל תפוגה אחד, במחיר של מסך הסכמה כל 90 ימים.

• אחרי שתוקף האסימון פג או שהוא בוטל, קריאות ל-API נדחות עם 401. הפנו את המשתמש שוב ל-/oauth/authorize.
• כשהמשתמש מאשר שוב את האפליקציה שלכם, Nodaro מעדכן את אישור הגישה שלו ומנפיק אסימון חדש. אסימונים קודמים נשארים בתוקף עד שהם פגים או מבוטלים, ולכן שמרו רישום של האסימונים שנמצאים בשימוש.
• כדי להוסיף הרשאה, שלחו את המשתמש דרך כתובת ההרשאה עם scope רחב יותר. אישור הגישה הקיים מורחב.

שמירה בטוחה של אסימונים

• שמרו את האסימונים בשרת שלכם. לעולם אל תשימו אסימון גישה ב-localStorage, ב-sessionStorage או בעוגייה ש-JavaScript יכול לקרוא.
• הצפינו את האסימונים באחסון אם הפלטפורמה שלכם תומכת בזה. Nodaro שומר רק גיבוב SHA-256 של כל אסימון, ולכן אסימון יכול לדלוף רק אם מסד הנתונים שלכם דולף.
• לעולם אל תשתפו אסימון בין משתמשים. כל אסימון שייך למשתמש Nodaro אחד; שימוש בו בהקשר של משתמש אחר הוא באג הרשאות.

ביטול אסימון

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

await client.oauth.revoke(tokens.access_token)
// { success: true }

curl -X POST https://nodaro.example.com/v1/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{ "token": "ndr_app_..." }'

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

כשהמשתמש מבטל את הגישה

משתמשים יכולים גם לסיים בעצמם את הגישה של האפליקציה שלכם. בדף הגדרות › אפליקציות מחוברות (/settings/connected-apps) מופיעים כל האפליקציות ועוזרי ה-AI שיש להם גישה לחשבון של המשתמש. כל פריט מציג את השם והסוג שלו, מתי הוא חובר, מתי השתמשו בו לאחרונה ואת ההרשאות שיש לו. הכפתור ביטול גישה מבקש אישור, ואז מסיים מיד את אישור הגישה ואת כל האסימונים שהונפקו במסגרתו.

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

רק סשן מחובר בדפדפן יכול להציג את אישורי הגישה האלה או לבטל אותם. הנתיבים GET /v1/me/connected-apps ו-POST /v1/me/connected-apps/:id/revoke דוחים אסימון גישה של OAuth ואסימון API אישי עם 401, ולכן אפליקציה לא יכולה לקרוא את הרשימה וגם לא לשנות אותה. כדי לסיים מקוד את הגישה של האפליקציה שלכם, השתמשו בנקודת הקצה של הביטול שלמעלה.

אפליקציית דפדפן שבנויה על ה-SDK קוראת את אישורי הגישה האלה ומבטלת אותם עם client.connectedApps() ועם client.revokeConnectedApp(authorizationId), בעזרת הסשן של המשתמש עצמו (supabaseAuth). עם מפתח API או עם אסימון של אפליקציה, שתי המתודות נכשלות עם 401, ולכן לא ה-CLI ולא שרת ה-MCP מציעים אותן.

שגיאות

נקודת הקצה של האסימונים עונה בשגיאות OAuth סטנדרטיות:

שלב ההרשאה מציג את השגיאות האלה במסך ההסכמה עצמו, ואף פעם לא מפנה איתן:

קריאות ל-API עם אסימון הגישה יכולות להיכשל בשגיאות האלה:

ה-SDK זורק את מקרה ה-403 כ-ForbiddenError עם missingScope בעל טיפוס, כך שתוכלו להציע הסכמה מחדש בלחיצה אחת:

import { ForbiddenError } from "@nodaro/sdk"

try {
  await userClient.workflows.run(workflowId)
} catch (err) {
  if (err instanceof ForbiddenError && err.missingScope) {
    // Send the user back to /oauth/authorize with the broader scope list.
    redirectToConsent({ scopes: [...currentScopes, err.missingScope] })
    return
  }
  throw err
}

רשימת בדיקות אבטחה

• HTTPS בכל מקום. מופע ה-Nodaro, האפליקציה שלכם וכל כתובת הפניה משתמשים ב-https://. הכתובת http://localhost מיועדת רק לפיתוח מקומי.
• בדקו את state בכל קריאה חוזרת. צרו אותו לכל אישור גישה ושמרו אותו בסשן של המשתמש.
• שמרו את client_secret בשרת שלכם. לעולם אל תכללו אותו באפליקציית דפדפן, אל תרשמו אותו ביומן ואל תציגו אותו בהודעת שגיאה.
• החליפו את הסוד לפחות פעם בשנה, ומיד אם אתם חושדים בדליפה.
• רשמו רק כתובות הפניה שלכם. רשמו רק את הכתובות שאתם באמת משתמשים בהן.
• בקשו את מספר ההרשאות הקטן ביותר. הוסיפו הרשאה כשאתם בונים את היכולת שצריכה אותה.
• בטלו את האסימון בהתנתקות. קראו לנקודת הקצה של הביטול כשמשתמש מתנתק מהאפליקציה שלכם, כדי שאי אפשר יהיה להשתמש שוב באסימון שלו.
• טפלו ב-missingScope. הציעו למשתמש הסכמה מחדש, ולא דף כללי של ״אין הרשאה״.

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

לולאת הבדיקה המהירה ביותר דורשת מופע Nodaro עם יישומי מפתחים, כמו Nodaro Cloud או התקנה של מהדורת Business, ושרת קטן במחשב שלכם שמקבל את הקריאה החוזרת.

import express from "express"
import { createClient, StaticTokenAuth } from "@nodaro/sdk"

const NODARO_URL = "https://app.nodaro.ai" // or your Business edition install

const app = express()

app.get("/cb", async (req, res) => {
  const client = createClient({ baseUrl: NODARO_URL, auth: new StaticTokenAuth("") })
  const tokens = await client.oauth.exchangeCode({
    client_id: process.env.NODARO_CLIENT_ID!,
    client_secret: process.env.NODARO_CLIENT_SECRET!,
    code: req.query.code as string,
    redirect_uri: "http://localhost:8080/cb",
  })
  res.json(tokens)
})

app.listen(8080)

גילוי ורישום דינמי ללקוחות MCP

לקוחות MCP, כמו Claude, ChatGPT ו-Cursor, מוצאים בעצמם את נקודות הקצה של OAuth ויכולים לרשום את עצמם בזמן ריצה, בלי שמישהו ייכנס לדף יישומי מפתחים. את הצד של המשתמש מתאר הדף חיבור לקוח.

מסמכי גילוי

כל מסמך זמין גם עם הסיומת /mcp, כי חלק מהלקוחות המחמירים מנסים את הצורה הזאת קודם. כל ארבעת המסמכים זמינים גם במארח של Nodaro וגם במארח של ה-MCP. המנפיק הוא ה-PUBLIC_URL של המופע, https://app.nodaro.ai ב-Nodaro Cloud.

במטא־דאטה של שרת ההרשאות מופיעים:

• נקודות הקצה של ההרשאה, של האסימונים, של הרישום ושל הביטול;
• סוג התגובה code וסוג ה-grant authorization_code;
• PKCE בשיטה S256 בלבד;
• שיטת האימות client_secret_post בנקודת הקצה של האסימונים;
• כל ההרשאות, ב-scopes_supported.

רישום לקוחות דינמי

לקוח רושם את עצמו עם POST /v1/oauth/register (RFC 7591) ומקבל client_id שמתחיל ב-ndr_dcr_, ובנוסף client_secret. נקודת הקצה מקבלת עד 10 בקשות לדקה מכל כתובת IP. מנהל השרת של המופע מגדיר את MCP_DYNAMIC_REGISTRATION:

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

התוסף ל-Figma בהתקנה באירוח עצמי

התוסף של Nodaro ל-Figma רץ בתוך Figma ולא יכול לקבל הפניה. במקום זה הוא מתחבר בלחיצת יד בסגנון device flow: התוסף מציג למשתמש קוד קצר, המשתמש מאשר את התוסף במסך ההסכמה הרגיל ומקליד את הקוד הזה, ואז התוסף מקבל את האסימון שלו. האסימון הוא אסימון רגיל של יישום מפתחים, עם ההרשאות jobs:read, assets:read, assets:write ו-credits:read, ואפשר לבטל אותו כמו כל אסימון אחר.

כדי לאפשר לתוסף להתחבר להתקנה שלכם:

1. רשמו יישום מפתחים, בדף יישומי מפתחים או עם POST /v1/developer-apps. הוסיפו את <PUBLIC_URL>/v1/oauth/plugin/callback לכתובות ההפניה שלו, ובקשו את ארבע ההרשאות שלמעלה.
2. שימו את מזהה הלקוח של האפליקציה ב-FIGMA_PLUGIN_OAUTH_CLIENT_ID בשרת.

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