認証

Nodaro API へのリクエストは、すべて Authorization ヘッダーのベアラートークンで認証します。自分のサーバーが自分のアカウントで Nodaro を呼び出す場合は、個人用 API トークン（ndr_…）を使います。プロダクトがほかの Nodaro ユーザーの代わりに動作する場合は OAuth アクセストークン（ndr_app_…）を、セルフホスティングの Community エディションのインストール環境ではセッションの JWT を使います。

Authorization: Bearer ndr_4f1c…

使う認証情報の選び方

簡単な見分け方があります。サーバーが必要とする認証情報が 1 組だけで、同意画面も不要なら、API トークンを使います。多くの顧客がそれぞれ、自分のアカウントへのアクセスをあなたのアプリに許可する必要があるなら、OAuth を使います。

API トークンは、Nodaro Cloud と Business エディションで利用できます。Community エディションでは、代わりに、ログイン中のセッションのアクセストークンを使って、同じエンドポイントを呼び出します。エディションを参照してください。

API トークンを作成する

このページには、各トークンの名前、プレフィックス、レート制限、最終使用日時、作成日時が一覧表示されます。トークンの横にあるスイッチでトークンのオンとオフを切り替え、ゴミ箱のボタンでトークンを削除します。

API トークンのルール

• 1 つのアカウントにつき最大 10 個：有効かどうかにかかわらず数えます。無効にしたトークンも数に含まれるので、枠を空けるには削除してください。11 個目のトークンは、400 limit_reached で拒否されます。
• 有効期限も利用額の上限もありません：トークンは、無効にするか削除するまで使えます。トークンを削除すると、すぐに取り消されます。
• トークンはあなたとして動作します：トークンによる呼び出しは、すべてあなたのアカウントとして実行され、あなたのクレジットを消費します。
• ログインに使うプロバイダーで再確認されることはありません：ID プロバイダーからアカウントが削除されても、その前に作成したトークンは、取り消すまで使え続けます。すべてのトークンを、期限のない認証情報として扱ってください。

トークンを一部のワークフローに限定する

トークンは、特定のワークフローのリストに限定できます。これを、トークンのワークフロースコープと呼びます。スコープを設定したトークンは、リストにあるワークフローだけを実行、確認でき、それ以外のワークフローでは 403 forbidden が返されます。リストが空の場合、トークンは、あなたが所有するすべてのワークフローを実行できます。

スコープは、下のエンドポイントでトークンを作成または更新するときに、workflowIds フィールドで設定します。リストに入れられるのは、個人スペースにあるワークフローだけです。ワークスペースにあるワークフローを指定すると、400 invalid_workflow が返されます。

コードからトークンを管理する

この 4 つのルートは、ログイン中のセッションからしか使えません。API トークンではなく、セッションの JWT を送ってください。個人用 API トークンや OAuth トークンは、403 forbidden で拒否され、「API token management is only available from a logged-in session」というメッセージが返されます。Community エディションのインストール環境では、作成と一覧表示のルートが、required_edition: "business" とともに 403 edition_required を返します。

トークンを 1 つのワークスペースに紐付けるには、トークンをワークスペースに紐付けるを参照してください。

トークンを送る

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

組織に属するアカウントでは、同じレスポンスに、そのアカウントが所属する組織とワークスペースも含まれます。ワークスペースと組織を参照してください。

SDK は認証プロバイダーからトークンを受け取るので、トークンの取得方法を自分で選べます。

CLI は、トークンを ~/.config/nodaro/config.json に、ファイルモード 0600 で保存します。--profile と --base-url を付けると、セルフホスティング環境用に 2 つ目のログインを保持できます。たとえば nodaro auth login --profile local --base-url http://localhost:3000 です。

OAuth アクセストークン

ユーザーがそれぞれ自分の Nodaro アカウントをあなたのプロダクトに接続する場合は、OAuth を使います。あなたのサーバーは、認可コードを、ndr_app_ で始まるアクセストークンと交換します。トークンの有効期間は 90 日で、リフレッシュトークンはありません。期限が切れたら、ユーザーにもう一度同意画面を通ってもらいます。

OAuth トークンには、ユーザーが許可したスコープだけが含まれます。トークンにないスコープを必要とするルートは 403 insufficient_scope を返し、エラーの missingScope にそのスコープが示されます。ほとんどの API 連携で必要になるスコープは、次のとおりです。

個人用 API トークンとセッションの JWT には、スコープがありません。どちらも、あなた自身のアカウントとして動作します。フローの全体、すべてのスコープ、同意画面については、OAuth アプリを参照してください。

ログイン中のセッションが必要なルート

いくつかのルートは Nodaro の Web アプリのためにあり、API トークンと OAuth トークンのどちらも拒否します。

コードからワークフローを構築するには、ワークフローのエンドポイント、SDK、または MCP サーバーを使います。

クライアントを識別する

X-Nodaro-Client ヘッダーを送ると、Nodaro はその値を、そのリクエストが作成するすべてのジョブの発信元として記録します。

X-Nodaro-Client: sdk/1.10.0

認識される形式は、sdk/<version>、cli/<version>、extension/<name> の 3 つだけです。このヘッダーは認証されないため、それ以外の値は無視されます。@nodaro/sdk と @nodaro/cli はこのヘッダーを自動で送るので、ヘッダーが必要になるのは、REST API を直接呼び出す場合だけです。省略しても問題ありません。その場合、ジョブは一般的な API 呼び出しとして記録されます。

ブラウザーから呼び出す場合は、このヘッダーを送らないでください。ブラウザーの Origin ヘッダーがすでにサイトを示しており、Nodaro はそちらを優先します。SDK は、ブラウザーで動作しているときは、このヘッダーを自動で省きます。

トークンはサーバーに置く

ブラウザーのコードに入れたトークンは、開発者ツールを使えば誰でも読み取れ、あなたのクレジットを消費できてしまいます。トークンは、サーバーのルート、エッジ関数、またはプラットフォームのシークレットストアに置き、ブラウザーはあなたのサーバーとだけ通信するようにします。

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

たとえば Next.js では、ルートハンドラーの中で、NEXT_PUBLIC_ プレフィックスの付かない環境変数からトークンを読み取ります。OAuth トークンを使ってブラウザーから Nodaro を呼び出す場合は、開発者アプリの許可するオリジンに、サイトのオリジンを追加してください。

トークンでセルフホスティング環境を接続する

個人用 API トークンは、セルフホスティング環境の生成を Nodaro Cloud で実行するための、いちばん簡単な方法でもあります。セルフホスティング環境で、NODARO_CLOUD_URL に Nodaro Cloud のアドレスを、NODARO_API_KEY にトークンを設定します。すると、すべての生成が Nodaro Cloud で実行され、料金はトークンのアカウントに請求されます。OAuth による接続は必要ありません。Nodaro Cloud への接続を参照してください。

請求アカウントが 1 つのデプロイメント

一部のデプロイメントには、すべてのユーザーの料金を支払う請求アカウントが 1 つだけあります。そのようなデプロイメントでは、次のようになります。

• トークンを作成できるのは、請求アカウントだけです。ほかのユーザーには 403 api_tokens_payer_only が返されます。既存のトークンは、引き続き、その所有者が一覧表示したり取り消したりできます。
• 「設定」に「APIトークン」のカードは表示されません。請求アカウントは、/settings/api を直接開きます。
• トークンによる呼び出しは、すべてデプロイメントの共有残高から支払われます。
• トークンでは、その共有残高を読み取れません。請求アカウントのトークンで残高を読み取ると 403 payer_balance_jwt_only が返され、デプロイメントの請求用ルートでは 403 payer_required が返されます。

エラー

すべてのエラーは、同じエンベロープを使います。完全な一覧は、エラーを参照してください。