理解する

基盤の考え方と責任分界

アプリを作る前に、基盤の機能と制約、アプリとの技術的な役割の分担を確認してください。登場する人ともの（利用者、組織の管理者、環境管理者など）は、用語集にあります。

基盤の機能

権限は、基盤がリクエストごとに判断します

基盤は、リクエストのたびに、その時点の権限を確認します。利用者の場合は、MFAも確認します。serviceの場合は、承認された範囲を確認します。

顧客アプリは、基盤が許可する範囲で操作します。利用者と役割の判断には、基盤が確認した資格を使います。

画面の表示の制御は、顧客アプリで実装します。

人もAIも、同じ権限の仕組みで扱います

AIエージェントが、利用者を助けて操作するときも、利用者の権限の範囲で操作します。MCPのツール名やreadOnlyHintは、権限を与えるものではありません。

AIが、人とは別の専用の経路で操作する場合は、基盤が信頼する入口と、利用者の委任の記録で、利用者に結び付けます。呼び出し元の自己申告や、User-Agentで、人とAIを区別することは、ありません。MCPの接続キーと基盤APIの資格は区別します。管理サイトからの経路には人セッションを使う構成と機械資格を使う構成があり、利用環境での構成と反映状態を確認します。

AIには、人より厳しい制限がかかることがあります（提案を経由する、停止される、AI専用のレート上限など）。該当するエラーは、エラーと再試行にあります。

AIの設定も、基盤が許可する操作の範囲に従います。

更新の競合を検出し、二重の実行を防げます

更新と削除には、取得した版を指定します。他の更新と競合すると、基盤は412で知らせます。

再送キー（Idempotency-Key）またはattempt_idに対応する操作では、通信が途切れても、同じ操作を二重に実行せずに、結果を確認できます。対応しない操作と、その確認の方法は、共通ルールの「再送の方式」にあります。

競合後の差分確認と再適用の判断は、顧客アプリで行います。

画像は、管理された原本、または外部の原本への参照として扱います

アプリが送った原本は、基盤が管理します。Dropboxなどの原本は、複製せず、参照として関連付けます。関連を解除しても、外部の原本は削除されません。

外部の原本の配置、整理、バックアップは、原本の管理者が担います。

機能は、利用環境ごとに有効になります

有効な機能は利用環境ごとに確認します。利用できる範囲は、環境管理者から受け取ります。

セッションは、無操作の時間で切れます

新しいセッションの方式の稼働版（2026-10以降）では、ログインの直後の反映待ちはありません。セッションは、組織で決めた無操作の時間（初期値は15分）で切れ、成功した操作のたびに延びます。認証から12時間で、ログインのし直しが必要です。401のcodeで、トークンの取り直しと、ログインのやり直しを分けます。詳しくは、利用者として接続する。

試験提供の間は、仕様が変わることがあります

0.7.0-experimentalは、試験提供の版です。更新する前に、変更履歴で差分を確認してください。

技術的な役割の分担

以下は機能と必要な権限の区分です。担当する組織や人、運用・支援・原本保管の範囲は利用環境の取り決めで確認します。

責任は、次の4者に分かれます。

基盤の機能

• 権限の判断（リクエストごと）
• データの保持と、版の管理
• 画像の関連付けと、配信
• 変更の受付と、結果を確認する手段の提供

アプリで実装すること

• 画面と、業務のロジック
• トークンとキーの安全な保管（ブラウザーに置かない、ログに出さない）
• 競合、再送、失効のときの振る舞い
• 「権限なし」と「未接続」の区別など、利用者への正確な表示
• 外部に置く原本の管理（原本の管理者と共同）

管理権限が必要な操作

• 利用者と、表の権限の設定（管理権限のmanage_accessが必要。MFAが必要）
• serviceの承認

利用環境で確認すること

• 接続情報（接続先、client_id、redirect_uri、信頼するCA）
• 有効な機能と実稼働版
• 非公開情報の連絡方法と運用範囲（サポートと窓口）

提供範囲と準備中の機能

状態の読み方