OAuth アプリ
OAuth アプリを登録し、ユーザーを Nodaro の同意画面に送り、コードを 90 日間有効なアクセストークンと交換して、各ユーザーの代わりに API を呼び出します。
Nodaro Cloud · Business エディション で利用できます
OAuth アプリを使うと、あなたのプロダクトが、ほかの Nodaro ユーザーの代わりに Nodaro API を呼び出せます。各ユーザーは同意画面であなたのアプリを承認し、あなたのサーバーはその結果得られるコードをアクセストークンと交換します。そのトークンによる呼び出しは、そのユーザーとして、付与されたスコープの範囲内で行われます。Nodaro は、標準の OAuth 2.0 認可コードフローを実装しており、シークレットを保持できないクライアントには PKCE を使います。
開発者アプリは、Nodaro Cloud と Business エディションのインストール環境で利用できます。
OAuth か個人用 API トークンか
| 作っているもの | 使うもの | トークンの形式 |
|---|---|---|
| 自分のアカウントを使う、スクリプト、cron ジョブ、CI ジョブ、バックエンド | 個人用 API トークン | ndr_ の後に 16 進数 64 文字 |
| ユーザーがそれぞれ自分の Nodaro アカウントを持つ、ホスティング型のプロダクト | OAuth アプリ | ndr_app_ の後に 16 進数 64 文字 |
自分のアカウントだけで認証し、同意画面もユーザーごとの取り消しも不要な場合は、個人用 API トークンを使います。認証を参照してください。
次のような場合は、OAuth を使います。
- Web アプリ、SaaS、マーケットプレイスなど、ホスティング型のプロダクトを構築していて、ユーザーがそれぞれ自分の Nodaro アカウントを持っている。
- 各ユーザーが、自分のアカウントでできることの一部だけを、あなたのアプリに許可する。
- 各ユーザーが、ほかのアプリに影響を与えずに、いつでもあなたのアプリのアクセスを取り消せる。
フローの仕組み
- ユーザーが、あなたのサイトで Nodaro に接続をクリックします。
- あなたのサイトが、
client_id、redirect_uri、scope、stateを付けて、ブラウザーを Nodaro の/oauth/authorizeページに送ります。 - Nodaro は、必要であればログインの後に、同意画面を表示します。この画面には、あなたのアプリの名前、ロゴ、要求するスコープ、そしてアクセスを許可することになるアカウントが表示されます。別のアカウントを使用をクリックすると、ユーザーはログアウトし、同じ画面に戻ります。
- ユーザーが許可をクリックすると、Nodaro は 1 回限りの認可コードを作成します。
- ブラウザーが、
?code=...&state=...を付けて、あなたのredirect_uriに戻ります。 - あなたのサーバーが、
client_idとclient_secretを使って、POST /v1/oauth/tokenでコードをアクセストークンと交換します。 - あなたのサーバーが、ユーザーの代わりに、
Authorization: Bearer ndr_app_...を付けて Nodaro API を呼び出します。
アプリを登録する
開発者アプリを開く
対象の Nodaro インスタンスで、設定 › 開発者アプリ(/settings/developer-apps)を開き、アプリを作成をクリックします。
フォームに入力する
名前、リダイレクト URI、スコープを入力します。各フィールドは、下の表で説明します。
クライアントシークレットを保存する
アプリを作成しましたダイアログには、app_ で始まるクライアント ID と、sec_ で始まるクライアントシークレットが表示されます。シークレットが表示されるのは、これ 1 回だけです。ダイアログを閉じる前に、シークレットマネージャーにコピーしてください。Nodaro はそのハッシュしか保存しないため、二度と表示できません。
| フィールド | 必須 | ルール |
|---|---|---|
| 名前 | はい | 1〜100 文字です。同意画面に表示されます。 |
| 説明 | いいえ | 最大 500 文字です。同意画面で、名前の下に表示されます。 |
| リダイレクト URI | はい | 1 行に 1 つ、1〜10 個です。それぞれ https:// のアドレス、または開発用の http://localhost のアドレスです。Nodaro はバイト単位で比較し、ワイルドカードには対応していません。 |
| 許可するオリジン | いいえ | パス、クエリ、フラグメントを含まない、素のオリジンを最大 5 個までです。フロントエンドがブラウザーから Nodaro を呼び出す場合(CORS)にだけ必要です。 |
| 要求するスコープ | はい | 少なくとも 1 つです。これは、あなたのアプリが要求できる上限です。ユーザーはこれより少なく許可でき、あなたのアプリはこれより多くを要求することはできません。 |
| ホームページの URL、ロゴの URL | いいえ | 作成後に、アプリのページで設定します。それぞれ https:// または http://localhost のアドレスです。正方形のロゴが最も見栄えがよくなります。 |
アプリを管理する
- シークレットを紛失したときや、日常的なセキュリティ対策として、アプリのページでシークレットを再発行します。古いシークレットはその時点で使えなくなるため、稼働中のすべてのサービスの設定を、すぐに更新してください。
- アプリを削除すると、そのアプリに発行されたすべてのアクセストークンが取り消されます。承認していたユーザーは、もう一度接続する必要があります。
- アプリは 1 ユーザーにつき 5 個までです。自己登録した MCP クライアントは同じ一覧に表示されますが、この上限には含まれません。
- コードからは、SDK の
client.developerAppsが、アプリの作成、更新、削除、シークレットの再発行を行います。SDK を参照してください。 - 一部のデプロイメントでは、アプリを管理できるのは管理者だけです。その場合、管理者以外がアプリを作成、変更、削除したり、シークレットを再発行したりすると
403 developer_apps_admin_onlyが返され、開発者アプリページには代わりに通知が表示されます。自分のアプリは引き続き読み取れ、以前に作ったアプリはそのトークンで引き続き動作します。
スコープ
スコープは、あなたのアプリが要求する 1 つの権限です。実際に使うスコープだけを要求してください。ユーザーは、要求されたすべてのスコープを同意画面で目にするため、短いリストのほうが信頼を得やすくなります。
| スコープ | 同意画面での表示 | 許可される操作 |
|---|---|---|
workflows:read | ワークフローを読み取る | ワークフローの一覧表示、読み取り、エクスポートです。ユーザー自身が公開したアプリの一覧表示と読み取り(分析と収益を含む)、収益化のデフォルトの読み取りです。 |
workflows:write | ワークフローを作成・変更する | ワークフローの作成、更新、削除、インポート、移動、サブワークフローの作成です。アプリの公開、変更、削除、復元、お気に入り登録と、収益化のデフォルトの設定です。 |
workflows:execute | ユーザーに代わってワークフローを実行する | ワークフロー、公開アプリ、公開コンポーネントの実行、MCP を通じた単一の生成ノードの実行、プロンプトウィザードの使用です。アプリの実行の再試行、最終版のレンダリング、名前の変更、削除、復元、読み取りです。 |
jobs:read | ジョブのステータスと結果を読み取る | ジョブと、そのステータスと結果の読み取り、生成セッションの読み取り、アプリの実行の読み取り、Webhook エンドポイントの管理です。 |
assets:read | アップロードしたアセットを読み取る | ギャラリー、アップロード、お気に入り、アプリの実行、キャラクター、ロケーション、オブジェクト、クリーチャーと、ユーザーのパレットとムードボードの読み取りです。 |
assets:write | ライブラリの項目(アップロード、キャラクター、保存した投稿、コレクション、ノードプリセット)を追加・変更・削除する | メディアのアップロード、ジョブのお気に入り登録と評価、キャラクター、ロケーション、オブジェクトの作成と更新、パレットとムードボードの書き込み、ノードプリセットとそのフォルダーとお気に入りの書き込み、生成セッションの作成と整理です。 |
credits:read | クレジット残高を確認する | MCP を通じた、クレジット残高とクレジットの取引履歴の読み取りです。このスコープを確認する REST のルートはありません。 |
apps:read | 公開済みのアプリを読み取る | ユーザー自身の公開アプリとお気に入りのアプリの一覧表示と、アプリの入力の読み取りです。 |
pipelines:read | パイプラインを読み取る | ストーリーから動画へのパイプラインと、そのステータス、保留中の承認の読み取りです。 |
pipelines:execute | ユーザーに代わってパイプラインを実行する(クレジットが消費される場合があります) | パイプラインの開始、各ステージの実行、ステージからの分岐です。 |
pipelines:approve | ユーザーに代わってパイプラインのステージを承認する | ステージの出力の承認、ステージのチャットとシーン用ヘルパーの使用です。 |
presets:read | 保存済みのプリセットを読み取る | ユーザーのノードプリセット、プリセットのフォルダー、お気に入りのプリセットの読み取りです。組み込みのプリセットカタログは公開されており、スコープは不要です。プリセットの書き込みには assets:write が必要です。 |
workspaces:read | 所属しているワークスペースを確認する | ユーザーのワークスペースの一覧表示です。 |
workspaces:write | 作業先のワークスペースを選択する | アプリが動作するワークスペースの選択です。 |
- 一部のスコープは REST のルートを制御し、一部は MCP ツールを制御し、両方を制御するものもあります。MCP サーバーは、トークンにないスコープを必要とするツールを、すべて非表示にします。
- ルートが必要とするスコープを持たないトークンには
403 insufficient_scopeが返され、不足しているスコープはmissingScopeに示されます。エラーを参照してください。 - ワークスペースのスコープは、組織機能が導入される前に発行されたトークンには、決して追加されません。これらを付与するには、ユーザーにもう一度あなたのアプリを承認してもらう必要があります。
- 公開アプリの実行には、開始のために
workflows:executeが、進行状況の読み取りのためにjobs:readが必要です。アプリの実行の読み取りにはassets:readやworkflows:executeも使えるため、実行を開始するアプリは、いつでもその実行をポーリングできます。 GET /v1/app/:slugで公開アプリを読み込むには、スコープは必要ありません。- スコープが適用されるのは、OAuth アプリのトークンだけです。セッショントークンと個人用 API トークンでは、スコープは確認されません。
公開したアプリの管理
OAuth アプリのトークンでは、次の /v1/apps/* と収益化のルートでスコープが確認されます。
| スコープ | ルート |
|---|---|
workflows:write | POST /v1/apps/publish、PATCH と DELETE /v1/apps/:appId、POST /v1/apps/:appId/restore、お気に入りの切り替えの POST /v1/apps/favorite、PUT /v1/user/monetization-defaults。 |
workflows:read または apps:read | GET /v1/apps/mine、GET /v1/apps/by-workflow/:workflowId、GET /v1/apps/favorites、GET /v1/apps/browse?favoritesOnly=true。 |
workflows:read | GET /v1/apps/:appId/analytics(と /analytics/runs)、GET /v1/apps/:appId/earnings、GET /v1/user/earnings、GET /v1/user/monetization-defaults。 |
workflows:execute | POST /v1/app/:slug/run、POST /v1/app/:slug/runs、PATCH と DELETE /v1/app/:slug/runs/:runId、POST /v1/app/:slug/runs/:runId/resume、/render-final と /restore、DELETE /v1/app/:slug/runs/:runId/permanent、POST /v1/component/execute。 |
jobs:read、assets:read または workflows:execute | GET /v1/app/:slug/runs、GET /v1/app/:slug/runs/:runId、GET /v1/me/archived-runs。 |
マーケットプレイスのカタログである GET /v1/apps/browse と GET /v1/apps/by-slug/:slug/latest-version には、スコープは必要ありません。スコープを持たないトークンには、missingScope 付きの 403 insufficient_scope が返されます。
ユーザーを同意画面に送る
ユーザーが 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>| パラメーター | ルール |
|---|---|
client_id | あなたのアプリのクライアント ID です。 |
redirect_uri | 登録済みのリダイレクト URI のいずれか 1 つと、バイト単位で完全に一致する必要があります。一致しない場合は 400 invalid_redirect_uri で拒否されます。 |
response_type | 常に code です。同意画面は、それ以外の値を拒否します。 |
scope | 要求するスコープを、スペースまたは + で区切って指定します。アプリの要求するスコープの部分集合である必要があります。 |
state | 認可のたびに作成し、ユーザーのセッションに保持する、ランダムなトークンです。Nodaro はこれをそのまま返すので、必ず確認してください。 |
あなたのサーバーで 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>- まず
stateを確認します。ユーザーのセッションにある値と一致しない場合は、処理を止めてください。これは、クロスサイトリクエストフォージェリに対する防御です。 - コードの交換は、あなたのサーバーで行います。この呼び出しをブラウザーから行わないでください。開発者ツールを使えば、誰でもあなたの
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 で拒否されます。
ベリファイアとチャレンジを作成する
リダイレクトの前に、ランダムで高エントロピーな code_verifier を作成します。code_challenge は、そのベリファイアの SHA-256 ハッシュを base64url エンコードして導出します。
認可リクエストにチャレンジを付けて送る
認可 URL に code_challenge と code_challenge_method=S256 を追加します。
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トークンの交換にベリファイアを付けて送る
client_secret の代わりに code_verifier を送ります。
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 に、ユーザーを通してください。既存の認可が広がります。 - 自分のアプリケーションのための交換で得たトークンの有効期間は、デフォルトで 1 時間です。アプリケーションは、もう一度交換してトークンを取得します。
トークンを安全に保管する
- トークンはサーバーに置きます。アクセストークンを、
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 が返されるため、アプリがこの一覧を読み取ったり変更したりすることはできません。アプリ自身のアクセスをコードから終わらせるには、上記の取り消しのエンドポイントを使ってください。
SDK で構築したブラウザーアプリは、ユーザー自身のセッション(supabaseAuth)を使い、client.connectedApps() と client.revokeConnectedApp(authorizationId) でこれらの認可を読み取り、取り消します。API キーやアプリのトークンでは、どちらからも 401 が返されるため、CLI と MCP サーバーはこれらを提供していません。
エラー
トークンエンドポイントは、標準の OAuth のエラーで応答します。
| ステータス | エラー | 発生する状況 | 対処 |
|---|---|---|---|
400 | invalid_request | リクエストの形式が正しくないか、フィールドが不足しています。 | リクエストを修正してください。 |
401 | invalid_client(Unknown client) | client_id が、登録されているどのアプリとも一致しません。 | 設定のクライアント ID を確認してください。 |
401 | invalid_client(Bad client_secret) | シークレットが正しくありません。多くは、再発行後の古いシークレットです。 | 現在のシークレットを読み込み、サービスを再起動してください。 |
400 | invalid_grant | コードの発行から 10 分を超えている、すでに使われている、または redirect_uri が認可リクエストのものと異なります。 | 同じ URI を使って、ユーザーにもう一度同意画面を通ってもらってください。 |
400 | unauthorized_client | デプロイメントが MCP クライアントを指定していて、このクライアントはそれに含まれておらず、MCP を要求しています。 | デプロイメントが用意したクライアントを通じて接続してください。 |
認可のステップは、これらのエラーについては同意画面で応答し、リダイレクトは行いません。
| ステータス | コード | 発生する状況 | 対処 |
|---|---|---|---|
400 | invalid_redirect_uri | redirect_uri が、そのアプリに登録されていません。 | アプリのページで URI を追加してください。 |
400 | invalid_scope | 要求されたスコープが、アプリの要求するスコープに含まれていません。 | 先にそのスコープをアプリに追加してください。 |
404 | invalid_client | client_id が不明である、またはアプリが停止されています。 | クライアント ID とアプリの状態を確認してください。 |
403 | mcp_client_not_allowed | デプロイメントが MCP クライアントを指定していて、このクライアントはそれに含まれておらず、MCP を要求しています。 | デプロイメントが用意したクライアントを通じて接続してください。MCP クライアントを指定するデプロイメントを参照してください。 |
アクセストークンを使った API の呼び出しは、次のように失敗することがあります。
| ステータス | コード | 発生する状況 | 対処 |
|---|---|---|---|
401 | unauthorized | トークンの期限が切れている、取り消されている、または形式が正しくありません。 | ユーザーにもう一度同意画面を通ってもらってください。 |
403 | insufficient_scope | トークンに、ルートが必要とするスコープがありません。ボディの missingScope にそのスコープが示されます。 | より広いスコープで、ユーザーに同意画面を通ってもらってください。 |
403 | mcp_client_not_allowed | MCP クライアントを指定しているデプロイメントの MCP エンドポイントへの呼び出しで、指定されていないクライアントのトークン、またはクライアントのトークンではないベアラーが使われました。 | デプロイメントが用意したクライアントを通じて接続してください。 |
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 インスタンスと、自分のマシン上の小さなコールバックサーバーが必要です。
テスト用のアプリを登録する
リダイレクト URI が http://localhost:8080/cb で、スコープが workflows:read、workflows:execute、jobs:read のアプリを作成します。
ポート 8080 でコールバックサーバーを実行する
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)認可 URL を開いて許可をクリックする
インスタンス上で /oauth/authorize?client_id=app_...&redirect_uri=http://localhost:8080/cb&response_type=code&scope=workflows:read+workflows:execute&state=test123 を開きます。許可をクリックすると、コールバックサーバーがトークンの JSON を表示します。
実際のルートを呼び出す
GET /v1/projects/<id>/workflows のようなルートで、そのトークンを使い、データとともに 200 が返ることを確認します。
MCP クライアント向けのディスカバリーと動的登録
Claude、ChatGPT、Cursor などの MCP クライアントは、自分で OAuth のエンドポイントを見つけ、人が開発者アプリのページを開かなくても、実行時に自身を登録できます。ユーザー側の手順は、クライアントを接続するを参照してください。
ディスカバリードキュメント
| エンドポイント | 標準 | 目的 |
|---|---|---|
GET /.well-known/oauth-authorization-server | RFC 8414 | 認可、トークンの取得、登録、取り消しの場所です。 |
GET /.well-known/oauth-protected-resource | RFC 9728 | MCP のリソース https://mcp.nodaro.ai/mcp を、その認可サーバーに結び付けます。 |
各ドキュメントは、末尾に /mcp を付けた形式でも提供されます。一部の厳格なクライアントが、その形式を最初に試すためです。この 4 つはすべて、Nodaro のホストと MCP のホストのどちらからでも取得できます。発行者は、インスタンスの PUBLIC_URL で、Nodaro Cloud では https://app.nodaro.ai です。
認可サーバーのメタデータは、次を示します。
- 認可、トークン、登録、取り消しの各エンドポイント
- レスポンスタイプ
codeとグラントタイプauthorization_code S256方式だけの PKCE- トークンエンドポイントでの
client_secret_post認証方式 scopes_supportedに含まれるすべてのスコープ
セルフホスティングのデプロイメントは、代わりに自身のホスト上のパスで MCP を提供できます。デフォルトは https://<host>/v1/mcp です。パスで提供する MCPを参照してください。その場合、デプロイメントが自身のホストとして宣言したホストであれば、このフローのすべてのアドレスは、クライアントが接続したホスト上になります。
- エンドポイントの
401チャレンジにはresource_metadataが含まれます。保護されたリソースのドキュメントのアドレスで、https://<host>/.well-known/oauth-protected-resource/v1/mcpです。 - そのドキュメントとルートのドキュメントは、
resource: https://<host>/v1/mcpとauthorization_servers: ["https://<host>"]を示します。 - 認可サーバーのドキュメントは、ルートと
/v1/mcp付きの両方で、発行者がhttps://<host>で、すべてのエンドポイントがその下にあります。 GET /v1/oauth/authorizeは、ブラウザーをそのホストの同意画面に送ります。
ほかのホストには、PUBLIC_URL のアドレスが返されます。登録、リダイレクト URI の確認、PKCE は、どのホストでも同じです。トークンはホストに結び付きません。デプロイメントのどのホストで発行されたトークンも、ほかのホストで使えます。そこではパスが /mcp に代わるため、/mcp 付きのドキュメントは提供されません。
動的クライアント登録
クライアントは、POST /v1/oauth/register(RFC 7591)で自身を登録し、ndr_dcr_ で始まる client_id と client_secret を受け取ります。このエンドポイントが受け付けるのは、1 つの IP アドレスから 1 分あたり 10 リクエストまでです。インスタンスの運用者は、MCP_DYNAMIC_REGISTRATION を設定します。
| モード | 動作 |
|---|---|
allowlist(デフォルト) | MCP_DCR_ALLOWLIST にあるクライアント名だけが登録できます。それ以外は 403 client_not_allowed になります。 |
open | どのクライアントも登録できます。クライアント名とリダイレクト URI の組み合わせごとに、24 時間で未使用のまま保持できる登録は最大 5 件です(429 too_many_open_registrations)。 |
off | 登録が無効になります(403 dcr_disabled)。運用者が、代わりに固定のクライアント ID とシークレットを配布します。 |
MCP クライアントを指定しているデプロイメントは、モードにかかわらず、MCP の登録すべてに 403 dcr_disabled で応答します。MCP クライアントを指定するデプロイメントを参照してください。
自己登録したクライアントは、自分で名前を決めているため、同意画面では、Nodaro がその名前を検証していないことがユーザーに警告されます。宣言するスコープは参考情報にすぎません。アクセスを実際に決めるのはユーザーの同意であり、クライアントはどの有効なスコープでも要求できます。運用者向けの設定は、セルフホスティング環境での MCP を参照してください。
MCP クライアントを指定するデプロイメント
デプロイメントの運用者は、MCP_ALLOWED_CLIENT_IDS に、そこで MCP を使える開発者アプリのクライアント ID を設定できます。このリストがある場合:
- MCP エンドポイントは、指定されたクライアントのトークンだけを受け付けます。それ以外のベアラー、つまりほかのクライアントのトークン、ログイン中のセッション、個人用 API トークンには、
403 mcp_client_not_allowedが返されます。この確認は呼び出しのたびに行われるため、リストから外されたクライアントは、次の呼び出しで止まります。 - 指定されていないクライアントが MCP を要求すると、同意画面の前のサインインの時点で拒否されます。クライアントが MCP を要求するとは、MCP クライアントとして自己登録した場合、または
resourceパラメーター(RFC 8707)が MCP エンドポイントを指している場合です。URL ではないresourceも、MCP の要求として扱われます。 - 各ステップでの拒否。
GET /v1/oauth/authorizeは、ブラウザーをクライアントの登録済みのredirect_uriに戻し、error=unauthorized_client、error_description、リクエストのstateを付けます。同意画面は403 mcp_client_not_allowedで応答し、コードは発行されません。POST /v1/oauth/tokenは400 unauthorized_clientで応答するため、以前に発行されたコードでもトークンは得られません。 - ほかの開発者アプリは、これまでどおりサインインします。MCP を要求しない、指定されていないアプリは、REST API で使えるトークンを受け取ります。MCP エンドポイントは、そのトークンを拒否します。
不明なクライアントや、そのクライアントに登録されていない redirect_uri にリダイレクトされることはありません。同意画面は、これまでどおり独自のエラーを表示します。Nodaro が resource パラメーターを読むのは、この規則のためだけです。保存されることはなく、トークンがリソースに結び付けられることもありません。
自分のアプリケーションのための MCP トークン
自分のアプリケーションですでにユーザーをサインインさせているデプロイメントでは、そのアプリケーションのサーバーが、どのユーザーについても 同意画面なしで MCP のアクセストークンを取得できるようにできます。これは、アプリケーションが外部ログインの ID プロバイダーでもあるデプロイメントに適しています。サーバーは、ユーザーを示す署名付きアサーションをトークンエンドポイントに送り、トークンを受け取ります。これは RFC 7523 の JWT-bearer グラントです。
運用者は、デプロイメントの MCP クライアントのリストにある 1 つのクライアントについて、この交換をオンにします。それ以外では、トークンエンドポイントはこのグラントを、知らないグラントタイプと同じように扱い、400 invalid_request を返します。その 1 つのクライアントについては、/.well-known/oauth-authorization-server も grant_types_supported に urn:ietf:params:oauth:grant-type:jwt-bearer を含めます。それ以外の場合、このリストに含まれるのは authorization_code だけです。
リクエスト
POST /v1/oauth/token は、必ず自分のサーバーから、フォームエンコードまたは JSON で送ってください。
| パラメーター | 値 |
|---|---|
grant_type | urn:ietf:params:oauth:grant-type:jwt-bearer |
assertion | 下で説明する署名付きアサーションです。URL ではなく、必ずボディで送ってください。 |
client_id、client_secret | 交換がオンになっているクライアントです。シークレットは必須です。 |
resource | トークンの対象となる MCP エンドポイントで、デプロイメントが示すとおりに正確に指定します。MCP のアドレスに /mcp を続けたもの、またはパスで MCP を提供するデプロイメントでは、呼び出すホスト上の https://<host>/v1/mcp です。末尾のスラッシュは無視されます。 |
scope | 任意で、スペースで区切ります。クライアントの要求するスコープより広くはできません。省略すると、そのすべてを受け取ります。 |
POST /v1/oauth/token HTTP/1.1
Host: app.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id=app_0123456789abcdef0123456789abcdef
&client_secret=sec_example-not-a-real-secret
&assertion=<the signed assertion>
&resource=https%3A%2F%2Fmcp.example.com%2Fmcp
&scope=jobs%3Aread%20assets%3Aread{
"access_token": "ndr_app_<64 hex characters>",
"token_type": "Bearer",
"scope": "jobs:read assets:read",
"expires_in": 3600
}このトークンは、そのユーザーとあなたのクライアントのための通常のアプリトークンです。Authorization: Bearer … として MCP エンドポイントに送ってください。有効期間はデフォルトで 1 時間で、運用者は 5 分〜24 時間の範囲で設定できます。expires_in に有効期間が示されます。リフレッシュトークンはありません。トークンの期限が切れる前、または呼び出しが 401 を返したときに、もう一度交換してください。
アサーション
アサーションは、サーバーが HS256 とプロバイダーの secret で署名する JWT です。この secret は、プロバイダーのサインイン用アサーションと同じものです。アサーションには、次のクレームを含めます。
| クレーム | 規則 |
|---|---|
aud | プロバイダーの exchangeAudience です。サインイン用の audience は使えません。aud がサインイン用のオーディエンスを、単独で、または交換用のオーディエンスと並べて指定しているアサーションは拒否されます。 |
exp、iat | 短い有効期間です。exp から iat を引いた値は、プロバイダーの maxLifetimeSeconds(デフォルトは 300 秒)以下です。1〜2 分で十分です。 |
jti | アサーションごとに一意です。各 jti は、サインインと交換を通じて 1 回だけ受け付けられます。 |
email、email_verified、sub | ユーザーで、プロバイダーの claimMap が示すとおりです。アカウントは、サインインのアカウントのリンク方法の規則で見つけられます。アカウントのないユーザーには、email_verified が true のときにアカウントが作成されます。 |
import { SignJWT } from "jose"
import { randomUUID } from "node:crypto"
// The provider's secret and exchangeAudience, from your server's own settings.
const key = new TextEncoder().encode(process.env.NODARO_SSO_SECRET!)
async function nodaroMcpToken(person: { id: string; email: string }) {
const assertion = await new SignJWT({ email: person.email, email_verified: true, sub: person.id })
.setProtectedHeader({ alg: "HS256" })
.setAudience(process.env.NODARO_EXCHANGE_AUDIENCE!)
.setIssuedAt()
.setExpirationTime("2m")
.setJti(randomUUID())
.sign(key)
const res = await fetch("https://app.example.com/v1/oauth/token", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
client_id: process.env.NODARO_CLIENT_ID!,
client_secret: process.env.NODARO_CLIENT_SECRET!,
assertion,
resource: "https://mcp.example.com/mcp",
}),
})
if (!res.ok) throw new Error(`exchange refused: ${res.status} ${await res.text()}`)
return (await res.json()) as { access_token: string; expires_in: number }
}交換のエラー
エラーは、標準の OAuth のボディ { "error": "…", "error_description": "…" } を使います。
| ステータス | エラー | 発生する状況 |
|---|---|---|
400 | invalid_request | assertion など、一部が不足しています。交換がクライアントに対してオフの場合も、この応答になります。 |
401 | invalid_client | client_secret がない、または正しくありません。Nodaro は、アサーションを読む前にこれを確認します。 |
400 | invalid_target | resource がない、またはこのデプロイメントの MCP エンドポイントではありません。説明に、エンドポイントが示されます。 |
400 | invalid_scope | クライアントが要求できない scope です。 |
400 | invalid_grant | アサーションが拒否されました。署名が正しくない、aud が違う、アサーションの期限が切れているか有効期間が長すぎる、jti がない、メールアドレスがない、またはすでに使われたアサーションです。説明に、どれに当たるかが示されます。ユーザーをサインインさせられない場合や、ユーザーがあなたのアプリを取り消した場合も、この応答になります。 |
429 | slow_down | あなたのネットワークから、またはあなたのクライアントについて、1 分間に 300 回を超える交換がありました。Retry-After の秒数だけ待ってください。 |
503 | temporarily_unavailable | 現在、交換を確認できません。もう一度試してください。 |
500 | server_error | トークンを発行できませんでした。 |
invalid_grant のアカウントに関する結果は、すべて同じ説明になるため、エンドポイントからアカウントの有無が分かることはありません。オフの交換は、不明なグラントと同じように応答し、unsupported_grant_type や unauthorized_client を返すことはありません。これは、交換の対象に指定されていないクライアント、MCP クライアントのリストから外されたクライアント、停止されたクライアントにも当てはまります。
ユーザーに表示される内容
設定 › 接続済みアプリには、あなたのアプリがサインイン経由で接続済みとして表示されます。ユーザーがそこでアプリを取り消すと、そのトークンはすぐに使えなくなります。その後、交換でそのユーザーの新しいトークンを得ることはできません(invalid_grant)。あなたのアプリをもう一度接続できるのは、同じクライアントの認可コードフローを通じた、ユーザー自身の同意だけです。
セルフホスティング環境での Figma 用プラグイン
Nodaro の Figma 用プラグインは Figma の中で動作するため、リダイレクトを受け取れません。代わりに、デバイス方式のハンドシェイクで接続します。プラグインがユーザーに短いコードを表示し、ユーザーは通常の同意画面でプラグインを承認してそのコードを入力し、プラグインがトークンを受け取ります。このトークンは、スコープ jobs:read、assets:read、assets:write、credits:read を持つ、ごく普通の開発者アプリのトークンであり、ほかのトークンと同じように取り消せます。
自分のインストール環境にプラグインを接続させるには、次のようにします。
- 開発者アプリで、または
POST /v1/developer-appsで、開発者アプリを登録します。そのリダイレクト URI に<PUBLIC_URL>/v1/oauth/plugin/callbackを追加し、上記の 4 つのスコープを要求します。 - サーバーの
FIGMA_PLUGIN_OAUTH_CLIENT_IDに、そのアプリのクライアント ID を設定します。
この設定がない場合、プラグインの接続用ルートはすべて 503 plugin_connect_not_configured を返します。アプリにコールバック URI やスコープが不足している場合、ルートは 503 plugin_connect_misconfigured を返し、サーバーのログに、何が不足しているかが記録されます。
よくある質問
個人用 API トークンではなく OAuth が必要なのは、どんなときですか?
プロダクトがほかの人の Nodaro アカウントに対して動作し、各ユーザーがあなたのアプリを承認し、そのアクセスを取り消せる必要がある場合は、OAuth を使います。自分のアカウントだけを使うスクリプトやサーバーには、個人用 API トークンのほうが簡単です。
Nodaro の OAuth アクセストークンの有効期間は、どれくらいですか?
90 日です。Nodaro はリフレッシュトークンを発行しないため、トークンの期限が切れるか取り消されると、API の呼び出しは 401 を返し、ユーザーにもう一度同意画面を通ってもらうことになります。
Nodaro は PKCE に対応していますか?
はい、S256 方式だけに対応しています。モバイルアプリ、シングルページアプリ、CLI ツールは、クライアントシークレットの代わりに、認可リクエストで code_challenge を、トークンの交換でそれに対応する code_verifier を送ります。
クライアントシークレットを紛失した場合、どうなりますか?
Nodaro はシークレットのハッシュしか保存していないため、二度と表示できません。アプリのページでシークレットを再発行すると、新しいものが手に入ります。古いシークレットは、その時点で使えなくなります。
開発者アプリは、いくつ登録できますか?
1 ユーザーにつき 5 個です。自己登録した MCP クライアントは同じ一覧に表示されますが、この上限には含まれません。
ユーザーは、私のアプリに許可したアクセスを取り消せますか?
はい。ユーザーは「設定 › 接続済みアプリ」で、自分のアカウントにアクセスできるアプリであれば、どのアプリのアクセスでも取り消せます。その認可と、その認可のもとで発行されたすべてのトークンはすぐに使えなくなり、あなたの呼び出しは 401 を返します。ユーザーにもう一度同意画面を通ってもらってください。
関連ページ
認証
TypeScript SDK
クライアントを接続
エージェントスキル
ミニアプリの埋め込み
最終更新