# 認証

> 個人用 API トークン、OAuth アプリのトークン、セッションの JWT で Nodaro API の呼び出しを認証します。API トークンの作成、対象の限定、ワークスペースへの紐付け、取り消しも説明します。

Source: https://nodaro.ai/ja/docs/developers/api/authentication

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

```http
Authorization: Bearer ndr_4f1c…
```

## 使う認証情報の選び方
| あなたの状況 | 使うもの | トークンの形式 |
| --- | --- | --- |
| サーバー、cron ジョブ、CI パイプラインから、自分の Nodaro アカウントをスクリプトで操作する | 個人用 API トークン | `ndr_` の後に 16 進数 64 文字 |
| ほかのユーザーの Nodaro アカウントでワークフローを実行するプロダクトを構築する | OAuth アクセストークン | `ndr_app_` の後に 16 進数 64 文字 |
| セルフホスティングの Community エディションを自分用に運用する | 自分のセッションの JWT | `eyJ` で始まる JWT |

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

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

## API トークンを作成する
### APIトークンのページを開く
Nodaro にログインし、**設定 › APIトークン**を開きます。Nodaro Cloud では、このページは `https://app.nodaro.ai/settings/api` にあります。

### トークンを作成する
**トークンを作成**をクリックします。**APIトークンを作成**ダイアログで、自分で区別するための**名前**（`prod-scheduler` など）と、1〜120 の**レート制限（リクエスト／分）**を入力します。デフォルトは 1 分あたり 30 リクエストです。

### すぐにコピーする
**作成**をクリックし、トークンをシークレットストアにコピーします。トークンが表示されるのは 1 回だけです。Nodaro はトークンの SHA-256 ハッシュしか保存しないため、紛失したトークンは復元できません。その場合は、新しいトークンを作成してください。

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

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

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

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

## コードからトークンを管理する
| メソッド | パス | 内容 |
| --- | --- | --- |
| `POST` | `/v1/api-tokens` | トークンを作成します。ボディは `{ name, workflowIds, rateLimit }` です。トークン全体が表示されるのは、このレスポンスだけです。 |
| `GET` | `/v1/api-tokens` | トークンを、その設定とワークスペースの紐付け（`workspaceId`）とともに一覧表示します。トークン自体が返されることはありません。 |
| `PATCH` | `/v1/api-tokens/:id` | 名前、ワークフロースコープ、レート制限、有効フラグ、ワークスペースの紐付けを変更します。 |
| `DELETE` | `/v1/api-tokens/:id` | トークンを削除します。トークンはすぐに使えなくなります。 |

この 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 つのワークスペースに紐付けるには、[トークンをワークスペースに紐付ける](https://nodaro.ai/docs/developers/api/workspaces#bind-a-token-to-a-workspace)を参照してください。

## トークンを送る
`GET /v1/me` は、有効なトークンであれば、そのトークンの背後にあるアカウントを返します。そのため、トークンを確認するいちばん手軽な方法です。トークンがない場合、無効な場合、取り消されている場合は、`401 unauthorized` が返されます。

**curl**

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

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

**TypeScript SDK**

```ts

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)
```

**CLI**

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

組織に属するアカウントでは、同じレスポンスに、そのアカウントが所属する組織とワークスペースも含まれます。[ワークスペースと組織](https://nodaro.ai/docs/developers/api/workspaces)を参照してください。

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

| プロバイダー | 用途 |
| --- | --- |
| `StaticTokenAuth` | サーバー上の固定のトークンです。API トークンまたは OAuth アクセストークンを使います。 |
| `supabaseAuth(supabase)` | Nodaro のインストール環境とログインを共有するブラウザーアプリです。セッションのトークンはリクエストのたびに読み取られるため、更新は自動で行われます。 |
| `CallbackAuth` | 独自の処理です。たとえば、トークンを更新するセッションストアです。コールバックが `null` を返すと、ヘッダーは送られません。 |

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 連携で必要になるスコープは、次のとおりです。

| スコープ | 許可される操作 |
| --- | --- |
| `workflows:read` | ユーザーのワークフローの読み取りです。`GET /v1/workflows`、`GET /v1/workflows/:id`、そのエクスポート、プロジェクトごとの一覧が対象です。 |
| `workflows:write` | ワークフローの作成、変更、インポート、削除です。 |
| `workflows:execute` | `POST /v1/workflows/:id/run` による、ワークフローの実行です。 |
| `jobs:read` | ジョブのステータスと結果の読み取りです。一括ポーリングも含みます。 |

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

## ログイン中のセッションが必要なルート
いくつかのルートは Nodaro の Web アプリのためにあり、API トークンと OAuth トークンのどちらも拒否します。

| ルート | トークンへの応答 |
| --- | --- |
| `/v1/api-tokens`（トークンの管理） | `403 forbidden` |
| `/v1/billing/*`（購入手続き、クレジットのチャージ、自動チャージ、購入履歴） | `403 forbidden` |
| ノードプリセットへの書き込み | `403 forbidden` |
| `/v1/copilot/*`（[ワークフロー Copilot](https://nodaro.ai/docs/get-started/workflow-copilot)） | `403 in_app_only` |
| `/v1/http-credentials`（**Webhook 出力**（Webhook Output）ノード用に保存したキー） | `403 in_app_only` |

コードからワークフローを構築するには、[ワークフローのエンドポイント](https://nodaro.ai/docs/developers/api/workflows)、[SDK](https://nodaro.ai/docs/developers/sdk)、または [MCP サーバー](https://nodaro.ai/docs/mcp)を使います。

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

```http
X-Nodaro-Client: sdk/1.10.0
```

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

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

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

```text
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 への接続](https://nodaro.ai/docs/self-hosting/cloud-connect)を参照してください。

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

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

## エラー
| ステータス | コード | 意味 |
| --- | --- | --- |
| 400 | `limit_reached` | 有効かどうかにかかわらず、すでに 10 個のトークンがあります。先に 1 つ削除してください。 |
| 400 | `invalid_workflow` | `workflowIds` のエントリが、個人スペースにあるワークフローではありません。 |
| 400 | `token_workspace_mismatch` | 1 つのワークスペースに紐付けたトークンが、別のワークスペースを指定する `X-Nodaro-Workspace` ヘッダーとともに送られました。 |
| 401 | `unauthorized` | トークンがないか、無効か、期限切れか、取り消されています。 |
| 403 | `forbidden` | トークンのワークフロースコープにこのワークフローが含まれていないか、ルートにログイン中のセッションが必要です。 |
| 403 | `insufficient_scope` | OAuth トークンに、ルートが必要とするスコープがありません。`missingScope` にそのスコープが示されます。 |
| 403 | `in_app_only` | このルートは、Nodaro の Web アプリ専用です。 |
| 403 | `edition_required` | このルートには、より上位のエディションが必要です。`required_edition` に、最低限必要なエディションが示されます。 |
| 403 | `api_tokens_payer_only` | 請求アカウントが 1 つのデプロイメントでは、その請求アカウントだけがトークンを作成できます。 |
| 403 | `sso_required` | デプロイメントがログインを自身の ID プロバイダーに限定しており、このセッションのアカウントは、その ID プロバイダー経由で作成されていません。API トークンと OAuth トークンは影響を受けません。 |

すべてのエラーは、同じエンベロープを使います。完全な一覧は、[エラー](https://nodaro.ai/docs/developers/api/errors)を参照してください。

## Frequently asked questions

### Nodaro の API キーは、どうやって取得しますか？

Nodaro にログインし、「設定 › APIトークン」を開いて「トークンを作成」をクリックします。トークンに名前とレート制限を設定してから、コピーしてください。トークンは ndr_ で始まり、表示されるのは 1 回だけです。

### Nodaro の API トークンに有効期限はありますか？

いいえ。個人用 API トークンは、無効にするか削除するまで使え、利用額の上限もありません。パスワードと同じように保管し、不要になったら削除してください。

### API トークンと OAuth のどちらを使うべきですか？

自分のサーバーから自分のアカウントで Nodaro を呼び出す場合は、個人用 API トークンを使います。プロダクトを構築し、そのユーザーがそれぞれ自分の Nodaro アカウントを接続する場合は、OAuth を使います。

### セルフホスティングの Community エディションでも API を使えますか？

はい。API トークンは、Nodaro Cloud と Business エディションで利用できます。Community エディションのインストール環境では、代わりに、ログイン中のセッションの JWT をベアラートークンとして送ります。

### ブラウザーから Nodaro API を呼び出せますか？

個人用 API トークンは、ブラウザーのコードに決して入れないでください。ブラウザーでは誰でも読み取れてしまいます。自分のサーバーから Nodaro を呼び出すか、OAuth を使い、開発者アプリにサイトのオリジンを登録してください。