ワークスペースと組織

ワークスペースは、組織のメンバーが一緒に作業する場所です。学校ならクラス、会社ならチームにあたります。API のリクエストは、X-Nodaro-Workspace ヘッダーにその ID を送信すると、1 つのワークスペースで操作します。組織のエンドポイントは、それを取り巻くすべてを管理します。組織、メンバー、招待、参加コード、共有、予算、使用状況です。

組織は Nodaro Cloud の機能で、インスタンスごとに有効にします。有効になっていない環境では、以下のエンドポイントは存在せず、ヘッダーも無視されます。セルフホスティングのビルドには、組織は含まれません。概念については、ワークスペースを参照してください。

ワークスペースで操作する

X-Nodaro-Workspace: 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34

このヘッダーが行うのは、次の 2 つだけです。一覧がどのワークスペースを返すかと、作成したものがどこに置かれるかです。アクセス権を与えることはありません。ID を指定して何かを読み取る、更新する、削除する、実行するといった操作は、そのオブジェクト自身のワークスペースに従います。ヘッダーを送り忘れても自分の作業が見えなくなることはなく、偽装したヘッダーでほかの人の作業にアクセスすることもできません。

ヘッダーがない場合は、組織を持たないアカウントが常にそうであるように、自分の個人スペースで作業します。

curl -s https://app.nodaro.ai/v1/workflows \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "X-Nodaro-Workspace: 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34"

// Every request of this client acts in the workspace:
const classClient = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
  workspaceId: '6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34',
})

// Or derive a second client from an existing one:
const classroom = client.withWorkspace(workspaceId)
await classroom.workflows.run(workflowId) // lands in the class
await client.workflows.run(workflowId)    // lands in the personal space

nodaro --workspace 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34 workflows list   # this command only
export NODARO_WORKSPACE=6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34            # this shell or CI job
nodaro workspace use 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34                # saved on the profile
nodaro workspace current                                                # which one applies, and why

client.withWorkspace は、既存のクライアントを変更するのではなく、新しいクライアントを返します。そのため、同時に実行される 2 つの操作が、どちらのワークスペースにいるかで競合することはありません。個人スペースには null を渡します。CLI では、3 つの方法のうち、上にあるものほど優先されます。nodaro workspace use は、保存する前にワークスペースを確認します。

ヘッダーは、自分が属しているワークスペースに対してのみ送信してください。

2 つの場所では、古くなった選択が拒否されることはなく、締め出されることもありません。GET /v1/me と GET /v1/workspaces、そして招待を承認する操作です。そこでは、もう選択できなくなったワークスペースは、ヘッダーを送らなかった場合と同じように扱われます。これらは、どのワークスペースを選択できるかを教えてくれるエンドポイントなので、そこに一覧されなくなったら、キャッシュした選択をクリアしてください。

トークンをワークスペースに紐付ける

API トークンは、1 つのワークスペースに紐付けられます。紐付けた後は、すべてのリクエストでそのヘッダーを送ったかのように動作し、別のワークスペースを明示的に指定したヘッダーには 400 token_workspace_mismatch が返されます。

# Bind
curl -X PATCH https://app.nodaro.ai/v1/api-tokens/$TOKEN_ID \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": "6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34"}'

# Unbind
curl -X PATCH https://app.nodaro.ai/v1/api-tokens/$TOKEN_ID \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": null}'

トークンの管理には、ログイン中のセッションの JWT が必要です。API トークンや OAuth トークンでは 403 forbidden が返されます。トークンを紐付けられるのは、ヘッダーで選択できるワークスペースだけですが、紐付けの解除はいつでもできます。トークンの一覧表示では、紐付けが workspaceId として返されます。

作成の保存先

• ワークスペースの中では、作成したものはそのワークスペースに置かれ、個人スペースに置かれることはありません。プロジェクトを指定しない作成は、ワークスペースのプロジェクトに置かれます。ワークスペースにまだプロジェクトがない場合、作成は 409 workspace_has_no_default_project を返します。プロジェクトを指定すれば成功します。
• 指定するプロジェクトは、自分が操作しているワークスペースに属している必要があります。別のワークスペースや自分の個人スペースのプロジェクトを指定すると、404 Project not found が返されます。これは、存在しないプロジェクトを指定した場合と同じ応答なので、ヘッダーを使って何が存在するかを調べることはできません。
• プロジェクトの作成は、管理者だけに制限されることがあります。その場合、メンバーには 403 project_create_not_allowed が返されます。
• 組織は、個人スペースを閉じることができます。その場合、メンバーはワークスペースの中でのみ作成でき、ヘッダーなしでの作成には 403 personal_space_disabled が返されます。組織を持たないアカウントは、影響を受けません。

アーカイブしたワークスペースは読み取り専用

ワークスペースをアーカイブすると、中身はすべて読み取り可能なまま残り、新しい作業の追加だけが止まります。一覧表示は、これまでどおり動作します。プロジェクト、ワークフロー、インポート、サブワークフローのいずれであれ、作成はすべて 409 workspace_archived を返し、ワークスペースへの作業の移動も同様です。作業を外に移動することは、引き続き許可されます。アーカイブしたワークスペースを開く理由は、そこから作業を救い出すためだからです。ワークフローの共有のような、それ以外の書き込みには 403 workspace_archived が返されます。判定には、ステータスではなくコードを使ってください。

自分が誰か：GET /v1/me

GET /v1/me は、自分のプロフィールを返します。組織が有効なインスタンスでは、organizations、workspaces、lastWorkspaceId も含まれ、各エントリーには自分のロールとステータスが付きます。組織のエントリーには、その組織がワークスペースに使う語句のような、解決済みの vocabulary が含まれます。そのため、クライアントが「Class」や「Team」をハードコードする必要はありません。GET /v1/workspaces は、同じワークスペースの一覧を単独で返します。

組織のフィールドが取りうる、次の 3 つの状態を区別してください。

組織のエンドポイント

すべてのエンドポイントに認証が必要です。ボディは JSON で、レスポンスは { "data": … }、一覧は { "data": [ … ], "nextCursor": … } で、ID は UUID です。

組織

• 承認。新しい組織は、通常は pending から始まり、プラットフォームが承認すると active になります。待っている間、それが見えるのはオーナーだけで、ほかの人には見えず、中身も何も変更できません。作成した人に伝えておかないと、この待ち時間が失敗のように見えてしまいます。
• 学校には規約への同意が必要です。学校を作成するには acceptTerms: true が必要で、これによって、オーナーは生徒を登録する権限があることを確認します。これがないと、作成は 400 terms_required を返します。
• スラッグは、小文字、数字、ハイフンからなる 1〜50 文字です。指定するスラッグは、使われていない必要があります（409 name_taken）。指定しない場合は、名前から導き出されます。「Sunrise School」は sunrise-school になり、次は sunrise-school-2 になります。
• 組織の作成は、ユーザー 1 人につき 1 時間あたり数件までに制限されています。

メンバー

ワークスペース

ワークスペースのメンバー

組織のオーナーと管理者は、一覧に載らなくても、その組織のすべてのワークスペースの管理者です。ワークスペースに明示的に追加すると、代わりにその明示的なロールが与えられます。これが、組織の管理者が 1 つのクラスでは単なるメンバーになれる仕組みです。

招待

招待は、1 つのメールアドレスを対象にします。そのリンクには、メールの中にしか存在しないトークンが含まれ、招待された人は、ログインする前に、自分が何に招待されているかを確認できます。

• アドレスごとに、それぞれ 1 行が対応します。status は sent、link_only、failed のいずれかで、link は、そのアドレスにメールが送られなかった場合に含まれます。メールプロバイダーのないインストール環境では、すべてのアドレスが link_only として返されます。これらのリンクは表示してください。招待はどちらの場合も存在し、リンクがなければ誰もそこに到達できません。
• 招待は 14 日で期限切れになります。組織が送信できるのは、1 日 500 件までです（429 bulk_invite_cap_exceeded）。
• 同じアドレスを再度招待すると、2 件目を作成する代わりに、open 状態の招待が新しいトークンに切り替わります。
• すでにメンバーである人を招待すると、招待自体は消費されますが、ロールが変わったり、停止が解除されたりすることはありません。

参加コード

参加コードは 8 文字で、部屋の中で声に出して読み上げられる長さです。1 つのワークスペースに、単なるメンバーとして参加させるためのもので、停止を解除することはなく、組織が許可するメールドメインには従います。

1 つのワークフローを共有する

権限付与は、1 人に 1 つのワークフローへのアクセスを与えます。アクセスを追加することしかできず、取り除くことはできません。

• 共有できる人：作成者。管理者がメンバーの作業を編集できるワークスペースでは、その管理者。共同編集者が招待できるワークスペースでは、そのワークフローを編集できる人です。
• メールアドレスで追加する場合、どの組織のものであっても、アカウントのアドレスと照合されます。404 は、そのアカウントが存在しないことを意味し、それ以上の情報は開示されません。
• ワークスペースの外にいる人は、編集者の権限があっても、閲覧だけに制限されます。実行にはアクティブなメンバーシップが必要なので、外部の共同編集者がワークスペースのクレジットを消費することはありません。
• ワークフローの作成者や自分自身には、権限を付与できません（400）。権限付与は、承認のステップなしに即座に有効になります。
• canChangeVisibility、canShare、canRun は、それぞれ独立したルールです。1 つから別の 1 つを推測しないでください。

まったくアクセスできないワークフローは、存在しないワークフローと同じように 404 を返します。すでに見えていて、それ以上の権限が必要な場合にだけ、403 が返されます。ワークスペースに属するワークフローの実行には、編集権限とアクティブなメンバーシップが必要です。

監査ログ

監査ログは、組織が停止されている間も読み取り可能なままです。action は、プロダクトの成長とともに増えていくオープンなリストです。知っている操作は表示し、それ以外は生の値をそのまま表示してください。

ロールと設定

設定は階層化されています。ワークスペースの設定は組織の設定より優先され、組織の設定は、その組織の種類のデフォルトより優先されます。設定されていないキーには下の階層の値が使われ、false も有効な値として扱われます。

組織だけが持つ設定として、["school.example"] のような allowed_email_domains と、{ "workspace": "Cohort" } のような vocabulary_overrides もあります。どちらも、更新すると全体が置き換わります。

学校の初期設定は、管理者は編集可、ワークフローは非公開、メンバーは共有された作業を閲覧のみ、メンバーはプロジェクトを作成不可、上限は有効、個人スペースは有効、ワークスペースの管理者は招待可、共同編集者は招待不可、です。チームの初期設定は、管理者は閲覧のみ、ワークフローはワークスペースに公開、メンバーは共有された作業を編集可、メンバーはプロジェクトを作成可、上限は無効、個人スペースは有効、両方の招待設定が有効、です。

予算と使用状況

組織は、メンバーの作業の代金を、段階を追うごとに範囲が狭くなる 3 つの段階で支払います。

1. プール。組織は、独自のチェックアウトを通じて、組織全体で 1 つのプールにプリペイドのクレジットパックを購入します。
2. 割り当て。オーナーは、プールからワークスペースの予算にクレジットを移動します。プールは、ワークスペースが得た分だけ減少します。クレジットをプールに戻すこともできますが、割り当てを減らせるのは、そのワークスペースがすでに確保または使用した分までです。
3. メンバーの上限。ワークスペースの中では、管理者が 1 人のメンバーの利用額に上限を設定できます。上限は、ワークスペースの設定で有効になっている場合にのみ適用され、そのワークスペースで作業する組織の管理者には、決して適用されません。

ワークスペースの中で行われた作業は、そのワークスペースが支払い、メンバー自身のクレジットは使われません。どの階層でも、余裕は「割り当て」から「確保」と「使用」を引いた値です。これを超える実行は、開始前に 402 budget_exceeded または 402 member_cap_exceeded で拒否されます。

返金と異議申し立てでは、組織のプールから按分でクレジットが引き戻されますが、ゼロを下回ることはありません。組織を削除するには、先にすべてのワークスペースの割り当てを回収する必要があります。

自動化は、ワークスペースのクレジットを消費します。Webhook トリガー（Webhook Trigger）の URL はベアラー認証情報です。それを持っている人なら誰でも実行を開始でき、ワークスペース内のワークフローの実行は、そのワークスペースが支払います。Webhook、スケジュール、Telegram のいずれから始まった自動実行も、まずトリガーの作成者がそのワークフローを引き続き実行できるかを確認します。できなくなっている場合、自動化は停止し、実行履歴には run_requires_authenticated_member というコードの失敗エントリーが 1 件表示されます。

使用状況レポート

2 つの使用状況ルートは、指定した期間について、誰が何にいくら使ったかを答えます。

• 各行には、3 つのクレジットの数値があります。credits は、それまでに実行にかかった金額です。終わった実行では確定した金額、進行中の実行では保持されている確保分です。settledCredits と inFlightCredits は、その合計を内訳にしたものです。
• ワークスペースの残りより高くついた従量制の実行では、余裕分までが課金され、残りはプラットフォームが負担します。合計では、これが platformAbsorbedCredits として報告され、settledCredits から platformAbsorbedCredits を引いた分が、実際に予算に反映された金額です。予算でまかなえなかった承認済みアプリの上乗せ分も同様に負担され、appMarkupAbsorbedCredits として別に報告されます。
• グループが 5,000 件を超えるレポートは、truncated: true を返します。切り詰められるのはグループ化された行だけで、合計は期間全体をカバーします。
• 一般のメンバーには自分の実行しか見えず、メンバーごとのグループ化も拒否されます。ワークスペースの管理者には全員が見え、userId で絞り込めます。組織のレポートは、オーナーと組織の管理者のためのものです。
• CSV のエクスポートは、UTF-8、RFC 4180 で、改行は CRLF、バイトオーダーマークはありません。=、+、-、@ で始まるセルは、表計算ソフトで実行されないように、先頭にアポストロフィが付けられます。エクスポートは、ユーザーごとに 1 分あたり 10 回までに制限され、監査ログに記録されます。
• メンバーがアカウントを削除すると、その実行履歴も一緒に消え、レポートにはその分の欠落が生じます。そのワークフローとプロジェクトは、ワークスペースに残ります。

使用状況レポートのないインスタンスは 404 を返し、レポート機能がまだ利用できない間は 503 billing_unavailable を返します。

エラー

SDK、CLI、MCP から

• SDK：client.organizations と client.workspaces が、これらのエンドポイントをカバーします。レポート用の usage、usageRows、usageCsv も含みます。client.me() には、組織のフィールドが含まれます。
• CLI：nodaro org と nodaro workspace です。たとえば nodaro org invite <orgId> --email ada@school.example --workspace <id> や nodaro org usage <orgId> --from 2026-09-01 --to 2026-09-30 --group-by member --csv > september.csv です。invite コマンドは、アドレスごとに 1 行を出力し、メールが送られなかったアドレスには、リンクも表示します。
• MCP：list_workspaces と select_workspace ツールです。選択内容はセッションをまたいで記憶され、セッションごとに再確認されます。これらのツールを使う OAuth アプリには、workspaces:read と workspaces:write のスコープが必要です。

コマンドとメソッドの完全な一覧は、CLI と SDK を参照してください。