> For the complete documentation index, see [llms.txt](https://studio-docs.japan-ai.co.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.japan-ai.co.jp/toraburushtingu/permission-and-auth-errors.md).

# 権限・認証エラー

操作はできるはずなのに拒否される、API／SDKで401・403が返る、外部サービスの接続が使えない、またはPageを開いた後に再認証を求められるときの切り分けです。対象は利用者・管理者です。症状が似ていても、**利用者のロール、Project APIキー、外部接続、Pageセッション**は別の原因です。認証情報を取り替えたり権限を広げたりする前に、どの経路で失敗したかを分けます。

## 関連記事

* [組織・Project・Appの権限を理解する](/guan-li-yun-yong/understand-org-project-app-permissions.md)
* [接続の失効・担当者変更に対応する](/guan-li-yun-yong/handle-expired-connections-and-owner-changes.md)
* [Project APIキーを管理する](/guan-li-yun-yong/manage-project-api-keys.md)

## この記事の範囲

この記事は、ロール・APIキー・外部接続・Pageセッションに関する拒否または認証失敗を分けるための案内です。キーの発行・切替・失効は[Project APIキーを管理する](/guan-li-yun-yong/manage-project-api-keys.md)、外部接続の修復と引き継ぎは[接続の失効・担当者変更に対応する](/guan-li-yun-yong/handle-expired-connections-and-owner-changes.md)、Pageのアクセスモードの設定は[画面からPageを登録・公開する](/rupageskillrissu/register-and-publish-pages.md)で扱います。Page自体のビルド・表示失敗、通信障害、入力内容のエラーを、本記事だけで認証・権限の問題と断定しません。

## まず確認すること

* [ ] 失敗した対象（画面操作、外部連携、Page、API／SDK）と組織・Project・App名を特定しました。
* [ ] 操作した利用者、利用アカウント、APIキーの用途名、または接続名を区別して記録しました。
* [ ] HTTPステータス、表示メッセージ、発生日時、再現手順を控えました。
* [ ] APIキー、パスワード、トークン、Cookie、Secretの実値をログ・画面共有・問い合わせに含めていません。
* [ ] 接続・キーを削除、再発行、再認証する前に、影響する自動処理や利用者を確認しました。

> エラーを解消するために、他者の認証情報を受け取る、キーをブラウザ側コードへ入れる、全スコープのキーを作る、全員へ共有する、といった対応は行わないでください。必要な対象・操作・担当を絞って確認します。

## 症状別に切り分ける

| 症状・表示されるメッセージ                                                                    | 主な原因                                                                       | 確認・対処                                                                                                                                  | 詳しい記事                                                                                                                                                     |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 「この操作を行う権限がありません」「アクセスが拒否されました」「このエージェントを使用する権限がありません。管理者にお問い合わせください。」           | 組織ロール、Projectロール、IAM、個別リソースの共有・ポリシーのいずれかが不足                                | 対象の組織・Project・リソースと、閲覧／実行／編集など失敗した操作を分けます。管理者は基本ロール、Project参加、必要ならIAMと共有範囲を確認します。利用者は自己判断でロールを変更せず依頼します。                               | [組織・Project・Appの権限を理解する](/guan-li-yun-yong/understand-org-project-app-permissions.md)                                                                     |
| 画面は開くが編集・削除・設定変更だけができない                                                          | 閲覧・実行の権限はあるが、変更操作のロールまたはIAM権限が不足                                           | どのボタン・対象で失敗したかを記録します。Project参加だけ、または組織管理者であることだけを根拠に変更可能と決めつけません。最小限の必要な操作を管理担当者へ依頼します。                                                | [組織・Project・Appの権限を理解する](/guan-li-yun-yong/understand-org-project-app-permissions.md)                                                                     |
| API／SDKが401（Unauthorized）を返す、または「認証が必要です」                                        | 認証情報が未指定・形式不正・無効、または要求経路に必要な認証方式を渡していない可能性                                 | 実行先、認証方式、対象Projectを確認します。キー値を貼り直して共有せず、承認済みの保管先・設定先を確認します。再発行は、既存キーの失効・期限・用途を確認してから行います。                                               | [Project APIキーを管理する](/guan-li-yun-yong/manage-project-api-keys.md)                                                                                        |
| API／SDKが403（Forbidden）を返す                                                        | 認証済みでも必要なスコープや実行権限がない、またはキー・組織・作成者の状態が利用条件を満たさない可能性                        | 要求した対象・操作と、キーに設定したスコープを照合します。必要な範囲が不足している場合だけ、最小スコープ・新しい期限で新規キーを発行し、切替後に旧キーを失効させます。                                                    | [Project APIキーを管理する](/guan-li-yun-yong/manage-project-api-keys.md)                                                                                        |
| API／SDKが無効・期限切れのキーを示す応答を返す、または失効後に失敗する                                           | キー値の取り違え、削除・期限切れ、または作成者のProjectアクセス喪失など                                    | 応答本文を記録し、対象Project、キーの名前、期限、削除・失効の有無、作成者と利用システムを確認します。作成時にしか実値を確認できないため、失った実値を一覧から復元しようとせず、新しいキーを発行して安全に切り替えます。                        | [Project APIキーを管理する](/guan-li-yun-yong/manage-project-api-keys.md)                                                                                        |
| 「要再認証」「連携が無効になっています。同じアカウントで再認証してください。」または「認証に失敗しました。問題が解決しない場合は管理者にお問い合わせください。」 | 外部サービスの認証期限切れ・解除・アカウント変更、または外部サービス側の権限変更。App導入・更新で追加または変更されたコネクタが未設定の場合もある | 個人接続か共有接続か、接続先、接続名、認証したアカウントを確認します。個人接続は本人が同じアカウントで再認証します。共有接続は利用者が別の個人接続で置き換えず、管理者が影響範囲を確認して対応します。App導入・更新直後は、案内されたコネクタ要件と設定担当を確認します。 | [接続の失効・担当者変更に対応する](/guan-li-yun-yong/handle-expired-connections-and-owner-changes.md)                                                                     |
| Pageで操作中に認証を求められる、再読み込み後に利用できる／できない                                              | Pageのアクセスモードに応じたサインインまたはPageセッションが失効・無効になった可能性                             | まずPageのURL、アクセスモード、利用アカウント、直前の操作を確認します。再読み込みまたは案内された認証を一度行い、同じ症状が続く場合は繰り返さず、Page管理者へ連絡します。外部顧客認証のPageでは案内された認証経路を使います。                 | [画面からPageを登録・公開する](/rupageskillrissu/register-and-publish-pages.md)、[組織・Project・Appの権限を理解する](/guan-li-yun-yong/understand-org-project-app-permissions.md) |

## 401と403を読み分ける

HTTPステータスは切り分けの入口です。すべてのAPI・画面で原因を一意に決めるものではないため、レスポンス本文、実行経路、対象の操作も併せて確認します。

| 状態                | 基本的な意味                               | 最初に確認すること                                   |
| ----------------- | ------------------------------------ | ------------------------------------------- |
| 401（Unauthorized） | 認証情報がない、無効、またはその経路で認証できなかった可能性       | 認証方式、設定先、対象Project、認証情報の有効性を確認します。          |
| 403（Forbidden）    | 認証後でも許可されない、または保護された経路の利用条件を満たさない可能性 | 必要なスコープ、ロール、Project参加、キーの期限・作成者・組織状態を確認します。 |

Project APIキーを使う経路では、キーの未指定・無効・期限切れ・必要スコープの不足などが403となる実装もあります。反対に、公開APIの操作によっては、無効または未指定のAPIキーを401、必要スコープの不足を403として案内します。**401ならキーを作り直す、403なら権限を最大化する、と機械的に判断しないでください。** 要求先の仕様と、返されたメッセージを確認します。

## 原因を分ける手順

1. **人のロールかを確認します。** ブラウザで特定の編集・管理操作だけが失敗する場合は、組織ロール、Projectロール、IAM、共有範囲を確認します。Projectへの参加と、個別リソースの操作権限は別です。
2. **APIキーかを確認します。** API／SDKで失敗する場合は、対象Project、キーの用途名、期限、削除・失効、必要スコープ、設定先を確認します。キーの値やスコープは後から編集する前提にせず、変更が必要なら安全に新規発行・切替・旧キー失効を行います。
3. **外部接続かを確認します。** 「要再認証」「未連携」などでは、接続の所有者と外部サービス側のアカウント・権限を確認します。担当交代時、後任者は前任者の個人接続を引き継ぐのではなく、自分の接続を準備します。
4. **Pageセッションかを確認します。** Pageの表示・操作中だけに発生する場合は、アクセスモードに合うアカウントまたは外部認証を確認し、再読み込み・再認証後の状態を記録します。Pageを公開設定に変更して回避しません。
5. **再現範囲を確認します。** 同じ利用者だけか、同じProjectの全員か、同じ外部サービス・APIキー・Pageだけかを分けます。重複した再実行や複数のキー発行は避けます。

## よくある誤解

* **Projectに参加すれば全操作を実行できる**とは限りません。ロール、IAM、個別リソースの共有・ポリシー、外部サービス側の権限を別々に確認します。
* **APIキーがあればすべてのAPIを呼べる**とは限りません。対象Project、スコープ、有効期限、組織の利用条件が関係します。
* **「接続済み」なら外部処理は成功する**とは限りません。外部サービス側のデータ権限、認証アカウント、接続先の状態も確認します。
* **Pageで再認証されたら、権限を上げるべきである**とは限りません。アクセスモードとPageセッションの問題か、実行する機能の権限かを分けます。

## 管理者・サポートに相談する前に

次を記録します。詳しい収集方法は、[問い合わせに必要な情報を集める](/toraburushtingu/collect-info-for-support.md)を参照してください。

* 組織、Project、App／Page／APIの対象名、利用者またはキーの用途名（実値は除く）
* 失敗した操作・要求先、HTTPステータス、表示メッセージ、発生日時、再現手順
* 利用者のロール確認結果、必要な操作、個人／共有接続の別、再認証の実施有無
* APIキーでは期限・スコープ・削除／失効・切替状況、PageではURL・アクセスモード・再認証後の状態

## 次に読む記事

* [組織・Project・Appの権限を理解する](/guan-li-yun-yong/understand-org-project-app-permissions.md)
* [接続の失効・担当者変更に対応する](/guan-li-yun-yong/handle-expired-connections-and-owner-changes.md)
* [Project APIキーを管理する](/guan-li-yun-yong/manage-project-api-keys.md)
* [表示されない・参加できない](/toraburushtingu/not-visible-cannot-join.md)
