OAuth アプリ

OAuth アプリを使うと、あなたのプロダクトが、ほかの Nodaro ユーザーの代わりに Nodaro API を呼び出せます。各ユーザーは同意画面であなたのアプリを承認し、あなたのサーバーはその結果得られるコードをアクセストークンと交換します。そのトークンによる呼び出しは、そのユーザーとして、付与されたスコープの範囲内で行われます。Nodaro は、標準の OAuth 2.0 認可コードフローを実装しており、シークレットを保持できないクライアントには PKCE を使います。

開発者アプリは、Nodaro Cloud と Business エディションのインストール環境で利用できます。

OAuth か個人用 API トークンか

自分のアカウントだけで認証し、同意画面もユーザーごとの取り消しも不要な場合は、個人用 API トークンを使います。認証を参照してください。

次のような場合は、OAuth を使います。

• Web アプリ、SaaS、マーケットプレイスなど、ホスティング型のプロダクトを構築していて、ユーザーがそれぞれ自分の Nodaro アカウントを持っている。
• 各ユーザーが、自分のアカウントでできることの一部だけを、あなたのアプリに許可する。
• 各ユーザーが、ほかのアプリに影響を与えずに、いつでもあなたのアプリのアクセスを取り消せる。

フローの仕組み

1. ユーザーが、あなたのサイトで Nodaro に接続をクリックします。
2. あなたのサイトが、client_id、redirect_uri、scope、state を付けて、ブラウザーを Nodaro の /oauth/authorize ページに送ります。
3. Nodaro は、必要であればログインの後に、同意画面を表示します。この画面には、あなたのアプリの名前、ロゴ、要求するスコープ、そしてアクセスを許可することになるアカウントが表示されます。別のアカウントを使用をクリックすると、ユーザーはログアウトし、同じ画面に戻ります。
4. ユーザーが許可をクリックすると、Nodaro は 1 回限りの認可コードを作成します。
5. ブラウザーが、?code=...&state=... を付けて、あなたの redirect_uri に戻ります。
6. あなたのサーバーが、client_id と client_secret を使って、POST /v1/oauth/token でコードをアクセストークンと交換します。
7. あなたのサーバーが、ユーザーの代わりに、Authorization: Bearer ndr_app_... を付けて Nodaro API を呼び出します。

アプリを登録する

アプリを管理する

• シークレットを紛失したときや、日常的なセキュリティ対策として、アプリのページでシークレットを再発行します。古いシークレットはその時点で使えなくなるため、稼働中のすべてのサービスの設定を、すぐに更新してください。
• アプリを削除すると、そのアプリに発行されたすべてのアクセストークンが取り消されます。承認していたユーザーは、もう一度接続する必要があります。
• アプリは 1 ユーザーにつき 5 個までです。自己登録した MCP クライアントは同じ一覧に表示されますが、この上限には含まれません。
• コードからは、SDK の client.developerApps が、アプリの作成、更新、削除、シークレットの再発行を行います。SDK を参照してください。

スコープ

スコープは、あなたのアプリが要求する 1 つの権限です。実際に使うスコープだけを要求してください。ユーザーは、要求されたすべてのスコープを同意画面で目にするため、短いリストのほうが信頼を得やすくなります。

• 一部のスコープは REST のルートを制御し、一部は MCP ツールを制御し、両方を制御するものもあります。MCP サーバーは、トークンにないスコープを必要とするツールを、すべて非表示にします。
• ルートが必要とするスコープを持たないトークンには 403 insufficient_scope が返され、不足しているスコープは missingScope に示されます。エラーを参照してください。
• ワークスペースのスコープは、組織機能が導入される前に発行されたトークンには、決して追加されません。これらを付与するには、ユーザーにもう一度あなたのアプリを承認してもらう必要があります。
• 公開アプリの実行には、開始のために workflows:execute が、進行状況の読み取りのために jobs:read が必要です。

ユーザーを同意画面に送る

ユーザーが Nodaro に接続をクリックしたら、ブラウザーを次の URL に送ります。

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 は、error=access_denied、error_description、あなたの state を付けて、あなたの redirect_uri にリダイレクトします。これは異常ではなく、通常の結果として扱ってください。
• リダイレクト URI が登録されていない場合、同意画面はエラーページを表示し、許可の場合もキャンセルの場合も、どこにもリダイレクトしません。

コードをトークンと交換する

ユーザーが許可をクリックすると、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
}

• コードは 1 回だけ使えます。同じコードを 2 回目に交換しようとすると、400 invalid_grant が返ります。
• コードは、発行から 10 分で期限切れになります。コールバックで受け取ったら、すぐに交換してください。
• トークンエンドポイントは、JSON とフォームエンコードのボディの両方を受け付けます。application/x-www-form-urlencoded で POST する標準の OAuth クライアントも、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>"
  }'

コンフィデンシャルクライアントは、シークレットと PKCE のベリファイアの両方を送ってもかまいません。Nodaro は、送られたものをそれぞれ検証します。

トークンで API を呼び出す

ユーザーごとに、そのユーザーのアクセストークンを使ったクライアントを 1 つ作成します。

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 を使わない場合は、各 REST 呼び出しの Authorization: Bearer ヘッダーにトークンを送ってください。エンドポイントは、REST API のリファレンスにあります。

トークンの期限が切れたとき

アクセストークンの有効期間は 90 日です。Nodaro はリフレッシュトークンを発行しません。トークンの種類は 1 つ、保存する場所は 1 つ、期限のルールも 1 つで、その代わりに 90 日ごとに同意画面を通ることになります。

• トークンの期限が切れるか取り消されると、API の呼び出しは 401 を返します。ユーザーをもう一度 /oauth/authorize に送ってください。
• ユーザーがあなたのアプリをもう一度承認すると、Nodaro はその認可を更新し、新しいトークンを発行します。以前のトークンは、期限が切れるか取り消されるまで有効なままなので、どのトークンが使われているかを把握しておいてください。
• スコープを追加するには、より広い scope を付けた認可 URL に、ユーザーを通してください。既存の認可が広がります。

トークンを安全に保管する

• トークンはサーバーに置きます。アクセストークンを、localStorage、sessionStorage、JavaScript が読み取れるクッキーに、決して入れないでください。
• プラットフォームが対応していれば、トークンを保存時に暗号化します。Nodaro は各トークンの SHA-256 ハッシュしか保持していないため、トークンが漏れる経路は、あなた自身のデータベースの漏えいだけです。
• トークンをユーザー間で共有しないでください。各トークンは 1 人の 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 を返します。期限切れのトークンと同じように扱い、ユーザーにもう一度同意画面を通ってもらってください。

これらの認可を一覧表示したり取り消したりできるのは、ログイン中のブラウザーセッションだけです。OAuth アクセストークンや個人用 API トークンでは、GET /v1/me/connected-apps と POST /v1/me/connected-apps/:id/revoke から 401 が返されるため、アプリがこの一覧を読み取ったり変更したりすることはできません。アプリ自身のアクセスをコードから終わらせるには、上記の取り消しのエンドポイントを使ってください。

エラー

トークンエンドポイントは、標準の OAuth のエラーで応答します。

認可のステップは、これらのエラーについては同意画面で応答し、リダイレクトは行いません。

アクセストークンを使った API の呼び出しは、次のように失敗することがあります。

SDK は、この 403 のケースを、型付きの missingScope を持つ ForbiddenError としてスローするため、ワンクリックでの再同意を提供できます。

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 のインスタンス、あなたのアプリ、すべてのリダイレクト URI は https:// を使います。http://localhost は、ローカルでの開発専用です。
• すべてのコールバックで state を確認します。認可ごとに作成し、ユーザーのセッションに保持してください。
• client_secret はサーバーに置きます。ブラウザーアプリに同梱したり、ログに出力したり、エラーメッセージにそのまま含めたりしないでください。
• シークレットを再発行します。少なくとも年に 1 回、そして漏えいの疑いがあれば直ちに行ってください。
• 自分のリダイレクト URI だけを登録します。実際に使うアドレスだけを登録してください。
• 最小限のスコープだけを要求します。そのスコープが必要な機能を作るときに、スコープを追加してください。
• ログアウト時に取り消します。ユーザーがあなたのアプリからログアウトしたら、取り消しのエンドポイントを呼び出し、トークンが再利用されないようにしてください。
• missingScope を処理します。汎用的な「アクセスが拒否されました」ページではなく、ユーザーに再同意を提供してください。

フローをローカルでテストする

最も手早くテストするには、Nodaro Cloud や Business エディションのインストール環境のように、開発者アプリを持つ Nodaro インスタンスと、自分のマシン上の小さなコールバックサーバーが必要です。

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 クライアント向けのディスカバリーと動的登録

Claude、ChatGPT、Cursor などの MCP クライアントは、自分で OAuth のエンドポイントを見つけ、人が開発者アプリのページを開かなくても、実行時に自身を登録できます。ユーザー側の手順は、クライアントを接続するを参照してください。

ディスカバリードキュメント

各ドキュメントは、末尾に /mcp を付けた形式でも提供されます。一部の厳格なクライアントが、その形式を最初に試すためです。この 4 つはすべて、Nodaro のホストと MCP のホストのどちらからでも取得できます。発行者は、インスタンスの PUBLIC_URL で、Nodaro Cloud では https://app.nodaro.ai です。

認可サーバーのメタデータは、次を示します。

• 認可、トークン、登録、取り消しの各エンドポイント
• レスポンスタイプ code とグラントタイプ authorization_code
• S256 方式だけの PKCE
• トークンエンドポイントでの client_secret_post 認証方式
• scopes_supported に含まれるすべてのスコープ

動的クライアント登録

クライアントは、POST /v1/oauth/register（RFC 7591）で自身を登録し、ndr_dcr_ で始まる client_id と client_secret を受け取ります。このエンドポイントが受け付けるのは、1 つの IP アドレスから 1 分あたり 10 リクエストまでです。インスタンスの運用者は、MCP_DYNAMIC_REGISTRATION を設定します。

自己登録したクライアントは、自分で名前を決めているため、同意画面では、Nodaro がその名前を検証していないことがユーザーに警告されます。宣言するスコープは参考情報にすぎません。アクセスを実際に決めるのはユーザーの同意であり、クライアントはどの有効なスコープでも要求できます。運用者向けの設定は、セルフホスティング環境での MCP を参照してください。

セルフホスティング環境での Figma 用プラグイン

Nodaro の Figma 用プラグインは Figma の中で動作するため、リダイレクトを受け取れません。代わりに、デバイス方式のハンドシェイクで接続します。プラグインがユーザーに短いコードを表示し、ユーザーは通常の同意画面でプラグインを承認してそのコードを入力し、プラグインがトークンを受け取ります。このトークンは、スコープ jobs:read、assets:read、assets:write、credits:read を持つ、ごく普通の開発者アプリのトークンであり、ほかのトークンと同じように取り消せます。

自分のインストール環境にプラグインを接続させるには、次のようにします。

1. 開発者アプリで、または POST /v1/developer-apps で、開発者アプリを登録します。そのリダイレクト URI に <PUBLIC_URL>/v1/oauth/plugin/callback を追加し、上記の 4 つのスコープを要求します。
2. サーバーの FIGMA_PLUGIN_OAUTH_CLIENT_ID に、そのアプリのクライアント ID を設定します。

この設定がない場合、プラグインの接続用ルートはすべて 503 plugin_connect_not_configured を返します。アプリにコールバック URI やスコープが不足している場合、ルートは 503 plugin_connect_misconfigured を返し、サーバーのログに、何が不足しているかが記録されます。