אימות

כל בקשה ל-API של Nodaro מאומתת עם אסימון Bearer בכותרת Authorization. השתמשו באסימון API אישי (ndr_…) כשהשרת שלכם קורא ל-Nodaro בשם החשבון שלכם, באסימון גישה של OAuth (ndr_app_…) כשהמוצר שלכם פועל בשם משתמשי Nodaro אחרים, וב-JWT של הסשן שלכם בהתקנה של מהדורת Community באירוח עצמי.

Authorization: Bearer ndr_4f1c…

באילו פרטי גישה להשתמש

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

אסימוני API זמינים ב-Nodaro Cloud ובמהדורת Business. במהדורת Community, קראו במקום זאת לאותן נקודות קצה עם אסימון הגישה של הסשן המחובר שלכם. ראו את הדף מהדורות.

יצירת אסימון API

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

כללים לאסימוני API

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

הגבלת אסימון לתהליכים מסוימים

אפשר להגביל אסימון לרשימת תהליכים — זו מגבלת התהליכים שלו. לאסימון שנוצר בדף מפתחות API אין מגבלה כזאת: הוא יכול להריץ כל תהליך שבבעלותכם. אסימון בלי workflowIds הוא אסימון הגישה המלאה של החשבון.

קובעים את המגבלה בשדה workflowIds, עד 50 תהליכים, כשיוצרים או מעדכנים אסימון דרך נקודות הקצה שלמטה. שינוי במגבלה נכנס לתוקף בתוך דקה. אפשר לכלול ברשימה רק תהליכים מהמרחב האישי שלכם: תהליך שנמצא בסביבת עבודה נדחה עם 400 invalid_workflow.

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

• הנתיבים GET /v1/api/workflows, GET /v1/workflows ו-GET /v1/projects/:projectId/workflows מחזירים רק את התהליכים האלה. הנתיב GET /v1/executions מחזיר רק את ההרצות שלהם.
• הנתיבים GET /v1/api/schema, POST /v1/api/run, GET /v1/workflows/:id, GET /v1/workflows/:id/interface, POST /v1/workflows/:id/run, POST /v1/workflows/:id/render-final/estimate ו-GET /v1/workflows/:id/executions עונים רק עבור התהליכים האלה.
• הנתיבים GET /v1/api/status/:execId, GET /v1/api/result/:execId ו-GET /v1/workflow-executions/:id, עם הנתיבים /stream ו-/cancel שלו, עונים רק עבור הרצות של התהליכים האלה. בקשה להרצה שלא שייכת לכם נדחית עם 404.
• נתיבים שלא דורשים התחברות, כמו הגלריה הציבורית וקטלוגי המודלים והרכיבים, עונים כרגיל, כמו בלי אסימון.

כל בקשה אחרת נדחית עם 403 forbidden, עם ההודעה "This API key is limited to specific workflows, and this request is outside them. Use a key without a workflow limit for anything else." (מפתח ה-API הזה מוגבל לתהליכים מסוימים, והבקשה הזאת מחוצה להם. לכל דבר אחר השתמשו במפתח בלי מגבלת תהליכים). זה כולל תהליך אחר או את ההרצות שלו, עריכה או מחיקה של תהליך, נתיבי היצירה הישירים, העלאות, משימות, אפליקציות שפורסמו, MCP ושימוש כפרטי גישה לממסר (relay). הבקשה נדחית לפני שמשהו רץ, ולכן אין שריון ואין חיוב.

ניהול אסימונים מקוד

ארבעת הנתיבים האלה עובדים רק מתוך סשן מחובר, ולכן שלחו את ה-JWT של הסשן שלכם, לא אסימון API. אסימון API אישי או אסימון OAuth נדחה עם 403 forbidden, עם ההודעה "API token management is only available from a logged-in session" (ניהול אסימוני API זמין רק מתוך סשן מחובר). בהתקנה של מהדורת Community, נתיבי היצירה והרשימה מחזירים 403 edition_required עם required_edition: "business".

כדי לשייך אסימון לסביבת עבודה אחת, ראו בדף ה-API שיוך אסימון לסביבת עבודה.

שליחת האסימון

הנתיב GET /v1/me מחזיר את החשבון שמאחורי כל אסימון תקף, ולכן זו הדרך המהירה ביותר לבדוק אסימון. אסימון חסר, לא תקין או מבוטל נדחה עם 401 unauthorized.

curl https://app.nodaro.ai/v1/me \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "data": {
    "id": "5bf0d884-47b1-468e-a7b2-2433f957b267",
    "email": "ada@example.com",
    "displayName": "Ada",
    "avatarUrl": null,
    "tier": "pro",
    "isAdmin": false
  }
}

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

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const me = await client.me()
console.log(me.email, me.tier)

nodaro auth login --token "$NODARO_API_KEY"
nodaro auth status

בחשבון ששייך לארגון, אותה תגובה כוללת גם את הארגונים ואת סביבות העבודה שהחשבון שייך אליהם. ראו את דף ה-API סביבות עבודה וארגונים.

ה-SDK מקבל את האסימון מספק אימות, ולכן אתם בוחרים מאיפה האסימון מגיע:

ה-CLI שומר את האסימון ב-~/.config/nodaro/config.json עם הרשאות קובץ 0600. הוסיפו --profile ו---base-url כדי לשמור התחברות שנייה להתקנה באירוח עצמי, למשל nodaro auth login --profile local --base-url http://localhost:3000.

אסימוני גישה של OAuth

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

אסימון OAuth כולל רק את ההרשאות שהמשתמש אישר. נתיב שדורש הרשאה שאין לאסימון מחזיר 403 insufficient_scope, והשגיאה מציינת את ההרשאה ב-missingScope. ההרשאות שרוב האינטגרציות של ה-API צריכות:

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

נתיבים שדורשים סשן מחובר

כמה נתיבים קיימים בשביל אפליקציית הווב של Nodaro ודוחים גם אסימוני API וגם אסימוני OAuth:

כדי לבנות תהליכים מקוד, השתמשו בנקודות הקצה של התהליכים, ב-SDK או בשרת ה-MCP.

זיהוי הלקוח שלכם

שלחו כותרת X-Nodaro-Client, ו-Nodaro רושם אותה כמקור של כל משימה שהבקשה יוצרת:

X-Nodaro-Client: sdk/1.10.0

רק שלוש צורות מזוהות: sdk/<version>, cli/<version> ו-extension/<name>. כל ערך אחר לא נלקח בחשבון, כי הכותרת לא מאומתת. החבילות @nodaro/sdk ו-@nodaro/cli שולחות אותה בשבילכם, ולכן אתם צריכים אותה רק כשאתם קוראים ל-REST API ישירות. אין בעיה להשמיט אותה: משימות כאלה נרשמות כקריאות API כלליות.

קריאות מדפדפן לא צריכות לשלוח את הכותרת. כותרת ה-Origin של הדפדפן כבר מציינת את האתר, ו-Nodaro מעדיף אותה. ה-SDK משמיט את הכותרת אוטומטית כשהוא רץ בדפדפן.

שמירת האסימונים בשרת שלכם

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

Browser  ->  your server (holds NODARO_API_KEY)  ->  Nodaro API

ב-Next.js, למשל, קבלו את האסימון בתוך route handler ממשתנה סביבה בלי הקידומת NEXT_PUBLIC_. אם בכל זאת אתם קוראים ל-Nodaro מדפדפן עם אסימון OAuth, הוסיפו את ה-origin של האתר שלכם לרשימת המקורות המורשים של יישום המפתחים.

חיבור התקנה באירוח עצמי עם אסימון

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

פריסות עם חשבון חיוב אחד

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

• רק חשבון החיוב יכול ליצור אסימון. בקשה של כל אחד אחר נדחית עם 403 api_tokens_payer_only, ובעלי אסימונים קיימים עדיין יכולים לראות ולבטל אותם.
• הכרטיס מפתחות API לא מוצג בהגדרות. חשבון החיוב פותח את /settings/api ישירות.
• כל קריאה שאסימון מבצע משולמת ממאגר הקרדיטים של הפריסה.
• אסימון לא יכול לקרוא את המאגר הזה. קריאות יתרה שנעשות עם האסימון של חשבון החיוב נדחות עם 403 payer_balance_jwt_only, ונתיבי החיוב של הפריסה מחזירים 403 payer_required.

שגיאות

כל שגיאה משתמשת באותה מעטפת. ראו את דף ה-API שגיאות לרשימה המלאה.