OAuth ויישומי מפתחים

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

מתודות

הרשאות

אפליקציה מבקשת הרשאות, ומשתמש מאשר אותן. השרת מקבל את ההרשאות האלה:

הדף אפליקציות OAuth מציג מה כתוב במסך ההסכמה לכל הרשאה. קריאה בלי ההרשאה שהיא דורשת נכשלת עם ForbiddenError, והשדה missingScope של השגיאה מציין את ההרשאה החסרה. ראו את הסעיף הרשאות (scopes) והרשאות חסרות בדף אימות.

client.developerApps

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

developerApps.list()‎

מחזירה את רשימת האפליקציות שלכם.

list(): Promise<{ data: DeveloperApp[] }>

const { data: apps } = await client.developerApps.list()
const mine = apps.filter((app) => (app.kind ?? "user") === "user")

ל-DeveloperApp יש id, name, description, logoUrl, homepageUrl, redirectUris, allowedOrigins, scopesRequested, clientId, status (active, suspended או pending_review), kind, createdAt ו-updatedAt. הערך של kind הוא "user" באפליקציה שרשמתם. הערכים האחרים, dynamic_mcp, first_party_mcp ו-community_instance, מציינים לקוחות שרשמו את עצמם. רק אפליקציות מסוג "user" נספרות במגבלה של חמש אפליקציות.

developerApps.get(id)‎

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

get(id: string): Promise<{ data: DeveloperApp }>

const { data: app } = await client.developerApps.get(appId)

developerApps.create(input)‎

רושמת אפליקציה. התגובה כוללת את clientSecret. שמרו אותו עכשיו: השרת שומר רק גיבוב שלו.

create(input: CreateDeveloperAppInput): Promise<{ data: DeveloperApp & { clientSecret: string } }>

const { data } = await client.developerApps.create({
  name: "My integration",
  redirectUris: ["https://example.com/oauth/callback"],
  scopesRequested: ["workflows:read", "workflows:execute"],
})
console.log(data.clientId, data.clientSecret) // save both now

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

developerApps.update(id, input)‎

משנה אפליקציה. שלחו רק את השדות שאתם משנים; הכללים של create() חלים על כל אחד מהם.

update(id: string, input: UpdateDeveloperAppInput): Promise<{ data: DeveloperApp }>

await client.developerApps.update(appId, {
  redirectUris: ["https://example.com/oauth/callback", "https://staging.example.com/oauth/callback"],
})

developerApps.delete(id)‎

מוחקת אפליקציה.

delete(id: string): Promise<{ success: true }>

await client.developerApps.delete(appId)

כשהמזהה לא קיים או שהאפליקציה לא שלכם, המתודה זורקת NotFoundError.

developerApps.rotateSecret(id)‎

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

rotateSecret(id: string): Promise<{ clientSecret: string }>

const { clientSecret } = await client.developerApps.rotateSecret(appId)

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

client.oauth

נקודות הקצה של OAuth 2.0 שהשרת של האפליקציה שלכם קורא להן. שמות השדות כתובים ב-snake_case, כמו בתקן OAuth.

oauth.exchangeCode(input)‎

מחליפה את קוד ההרשאה מההפניה של מסך ההסכמה באסימון גישה (POST /v1/oauth/token). ה-SDK מוסיף בשבילכם את grant_type: "authorization_code".

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

exchangeCode(input: {
  client_id: string
  client_secret: string
  code: string
  redirect_uri: string
}): Promise<{ access_token: string; token_type: "Bearer"; scope: string; expires_in: number }>

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

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://example.com/oauth/callback",
})

// Act for the user who approved your app
const userClient = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(tokens.access_token),
})

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

oauth.revoke(token)‎

מבטלת אסימון גישה (POST /v1/oauth/revoke, לפי RFC 7009). המתודה תמיד מחזירה { success: true }, גם לאסימון לא מוכר, כי התקן אוסר לחשוף אם אסימון היה תקף.

revoke(token: string): Promise<{ success: true }>

await client.oauth.revoke(accessToken)

oauth.getAppInfo(clientId, redirectUri?)‎

מחזירה את הנתונים הציבוריים של אפליקציה למסך הסכמה (GET /v1/oauth/app-info). המתודה לא צריכה אסימון.

getAppInfo(clientId: string, redirectUri?: string): Promise<OAuthAppInfo>

const info = await client.oauth.getAppInfo(clientId, "https://yourapp.com/oauth/callback")
if (!info.redirectUriRegistered) throw new Error("Unregistered redirect URI")

בתגובה יש name, description, logoUrl, homepageUrl, scopesRequested ו-redirectUriRegistered. הערך של redirectUriRegistered הוא true רק לכתובת שרשומה בדיוק כפי שהיא, ו-null כשלא שולחים redirectUri. כך מסך הסכמה יכול לדחות הפניה לכתובת שלא נרשמה, בלי לחשוף את רשימת הכתובות.