Console セットアップガイド
Console（管理画面）でアプリケーション（クライアント）を作成し、API 利用に必要な認証情報とスコープを設定する手順を解説します。
概要
AgenticStar の API を利用するには、Console でアプリケーション（クライアント）を事前に作成する必要があります。クライアントには用途に応じて2つの認証パターンがあり、作成時に選択します。
- Console にログインできること（developer ロール以上）
- テナントの管理者から API 利用の許可を得ていること
詳細は認証ガイドを参照してください。
クライアントタイプの選択
クライアントの認証パターンは作成後に変更できません。用途に合わせて適切なタイプを選択してください。
| Authorization Code（AC） | Client Credentials（CC） | |
|---|---|---|
| 用途 | エンドユーザーがブラウザでログインして利用するアプリケーション | サーバー間通信やバッチ処理など、ユーザーが介在しないシステム連携 |
| 認証フロー | Authorization Code（+ PKCE） | Client Credentials |
| トークン | アクセストークン + リフレッシュトークン | アクセストークンのみ |
| サブタイプ | Confidential（シークレットあり）/ Public（PKCE のみ） | Confidential のみ |
| テナント要件 | すべてのテナントで作成可能 | Enterprise テナントのみ（SaaS テナントでは作成不可） |
SaaS テナントをご利用の場合、認証パターンの選択は表示されず、自動的に AC（Authorization Code）が適用されます。CC クライアントが必要な場合は、テナント管理者にお問い合わせください。
AC クライアント（Authorization Code）
エンドユーザーがブラウザでログインして利用するアプリケーション向けです。ユーザーはテナント選択→ログイン→認可画面を経て、アクセストークンが発行されます。
Confidential と Public の違い
Confidential
サーバーサイドアプリケーション向け。Client Secret を安全に保管できる環境で使用します。トークンエンドポイントへのリクエスト時に client_secret が必要です。
Public
SPA（Single Page Application）やモバイルアプリ向け。Client Secret を安全に保管できない環境で使用します。PKCE（S256）が必須となり、code_verifier / code_challenge によるチャレンジ検証で保護されます。
AC クライアントの作成手順
Console の「アプリケーション」メニューから「新規作成」をクリックして作成を開始します。
1. 基本情報の入力
| 項目 | 必須 | 説明 |
|---|---|---|
| アプリ名 | ✓ | アプリケーションの表示名（最大256文字）。ユーザーの認可画面にも表示されます。 |
| ロゴ | ✓ | アプリケーションのロゴ画像。認可画面やアプリ一覧に表示されます。 |
| 概要（短い説明） | ✓ | 50文字以内の簡潔な説明。アプリ一覧のカードに表示されます。 |
| 詳細説明 | ✓ | アプリケーションの詳細な説明。アプリ詳細ページに表示されます。 |
| サポートURL | サポートページの URL。 | |
| プライバシーポリシーURL | プライバシーポリシーの URL。認可画面に表示されます。 | |
| 利用規約URL | 利用規約の URL。認可画面に表示されます。 |
2. 公開ステータスの選択
アプリケーションの公開範囲を設定します。テナントタイプにより選択肢が異なります。
| ステータス | 利用可能 | 説明 |
|---|---|---|
| Development | SaaS / Enterprise | 開発中。作成者のみ利用可能です。新規作成時のデフォルトです。 |
| Public | SaaS | SaaS テナントのすべてのユーザーに公開されます。 |
| Private | Enterprise | Enterprise テナント内のユーザーに限定公開されます。 |
3. 技術設定
| 項目 | 必須 | 説明 |
|---|---|---|
| Client ID | — | 自動生成される UUID です。変更はできません。作成後にコピーして利用します。 |
| Client Type | ✓ | Confidential または Public を選択します。作成後に変更はできません。 |
| Redirect URIs | ✓ | 認可完了後のリダイレクト先 URL を1つ以上登録します。完全一致で検証されるため、正確な URL を入力してください。 |
| Web Origins | ※ | Public クライアントの場合のみ必須。CORS で許可するオリジン URL を登録します。Confidential クライアントの場合は自動設定されるため表示されません。 |
Redirect URI はセキュリティ上、完全一致で検証されます。開発環境用（http://localhost:3000/callback）と本番環境用（https://yourapp.com/callback）の両方を登録しておくことをお勧めします。ワイルドカードは使用できません。
4. スコープの選択
アプリケーションに必要な権限（スコープ）を選択します。スコープの詳細は「スコープ設定」セクションを参照してください。
5. 自社利用設定（Enterprise テナントのみ）
Enterprise テナントの場合、ユーザーに認可画面（同意画面）を表示するかどうかを選択できます。自社内の信頼されたアプリケーションであれば、認可画面をスキップすることでユーザー体験を向上できます。
SaaS テナントでは、認可画面は常に表示されます（変更不可）。これはサードパーティアプリケーションとして、ユーザーの明示的な同意を得るためです。
6. 作成の完了
「作成」ボタンをクリックすると、アプリケーションが作成されます。作成完了後、アプリ詳細画面に遷移します。ここで Client ID と Client Secret を確認できます（確認方法は「認証情報の確認」セクションを参照）。
Confidential / Public の選び方
Client Type は作成後に変更できません。アプリケーションの実行環境に合わせて選択してください。
| Confidential | Public | |
|---|---|---|
| 実行環境 | サーバーサイド（Node.js, Python 等） | ブラウザ（SPA）、モバイルアプリ |
| Client Secret | あり（トークン取得時に必要） | なし（発行されない） |
| PKCE | 任意（推奨） | 必須（S256 のみ対応） |
| Web Origins | 自動設定（入力不要） | 手動で登録が必要 |
Public クライアントは Client Secret がないため、PKCE（Proof Key for Code Exchange）による保護が必須です。認可リクエスト時に code_challenge（S256 方式）を送信し、トークンリクエスト時に code_verifier を送信します。S256 以外の方式（plain 等）には対応していません。
CC クライアント（Client Credentials）
サーバー間通信やバッチ処理など、エンドユーザーが介在しないシステム連携向けです。Client ID と Client Secret のみでアクセストークンを取得します。
CC クライアントは Enterprise テナントでのみ作成できます。SaaS テナントでは認証パターンの選択自体が表示されません。
CC クライアントには以下の特徴があります。
- 常に Confidential（Client Secret あり）
- 公開ステータスは Private 固定（Enterprise テナント内のみ）
- Redirect URI は不要（ブラウザリダイレクトなし）
- リフレッシュトークンは発行されない（有効期限切れ後は再取得）
- サービスアカウント（システム用のユーザー ID）が自動的に作成される
CC クライアントの作成手順
Enterprise テナントの Console で「アプリケーション」→「新規作成」から、認証パターンで「Client Credentials」を選択して作成します。
1. 基本情報の入力
AC クライアントと同じ基本情報に加え、以下の違いがあります。
- ロゴは任意（必須ではない）
- プライバシーポリシー URL / 利用規約 URL は不要（認可画面がないため）
- 公開ステータスの選択は不要（Private 固定）
- Redirect URI / Web Origins は不要
2. スコープの選択
CC クライアントでは、AC とは異なるスコープが選択可能です。詳細は「スコープ設定」セクションを参照してください。
3. サービスアカウント ID の設定
CC クライアントで API を呼び出す際、「誰として」操作するかを決めるサービスアカウント ID を設定します。詳細は「サービスアカウント ID」セクションを参照してください。
4. 作成の完了
作成後、アプリ詳細画面で Client ID と Client Secret を確認できます。Client Secret はシステム連携先に安全に保管してください。
サービスアカウント ID
CC クライアントで API を呼び出す際、AgenticStar 内部では「サービスアカウント」という仮想的なユーザーとして処理されます。このサービスアカウントの ID を設定する方法は2つあります。
| 既存ユーザーにリンク | サービスアカウント（手動設定） | |
|---|---|---|
| 使用場面 | 既存ユーザーの代理として API を呼び出す場合 | システム専用の独立した ID で API を呼び出す場合 |
| 設定方法 | ユーザーを検索して選択 | 組織（任意）、職種（任意）、自己紹介（任意）を入力 |
| 作成後の変更 | 変更不可 | 変更不可 |
サービスアカウントの ID 方式は作成後に変更できません。「既存ユーザーにリンク」を選ぶと、そのユーザーの会話履歴やファイルにアクセスできるため、特定ユーザーのデータを利用するバッチ処理に適しています。独立した ID を使う場合は、システム専用の会話空間が作成されます。
スコープ設定
スコープは、クライアントがアクセスできる API の権限範囲を定義します。クライアント作成時にスコープ一覧から必要なものを選択します。
スコープの仕組み
1. クライアントにスコープを割り当て Console でクライアント作成時に、必要なスコープを選択します。選択したスコープが「このクライアントで利用可能な権限の最大範囲」となります。
2. ユーザーのロールでフィルタリング（AC のみ） AC クライアントの場合、トークンに含まれるスコープは「クライアントに割り当てられたスコープ」と「ログインユーザーのロールで許可されたスコープ」の積集合（共通部分）になります。
3. トークンにスコープが含まれる API リクエスト時、アクセストークンに含まれるスコープが各エンドポイントの要求スコープと照合されます。
選択可能なスコープ
認証パターン（AC / CC）によって選択できるスコープが異なります。
| スコープ | AC | CC | 説明 |
|---|---|---|---|
openid | ✓ | ✓ | 必須スコープ。常に含まれ、選択解除はできません。 |
[Chat] | |||
chat:all | — | ✓ | チャット機能全般。CC クライアントのみ選択可能です。 |
[Agent] | |||
agent:all | ✓ | ✓ | エージェント機能全般。 |
[Admin] | |||
admin:all | ✓ | ✓ | 管理機能全般。admin ロールを持つユーザーのみ有効です。 |
[Develop] | |||
develop:all | ✓ | ✓ | 開発者機能。developer ロールを持つユーザーのみ有効です。 |
CC クライアントの自動スコープ
CC クライアントには、選択したスコープに加えて以下のスコープが自動的に付与されます。これらは選択画面には表示されませんが、トークンに含まれます。
| スコープ | 説明 |
|---|---|
cc:tenant | テナント情報をトークンに含めます。サービスアカウントが所属するテナントの識別に使用されます。 |
cc:profile | サービスアカウントのプロフィール情報をトークンに含めます。 |
ロールとスコープの関係（AC クライアント）
AC クライアントでは、ログインするユーザーのロールによって実際にトークンに含まれるスコープが変わります。スコープ選択画面では各スコープに必要なロールが表示されるため、「チェック」ボタンで各ロールがどのスコープを利用できるか確認できます。
| ロール | 利用可能なスコープ |
|---|---|
| user | agent:all |
| admin | agent:all, admin:all |
| developer | agent:all, develop:all |
:::example スコープのフィルタリング
クライアントに agent:all と admin:all を割り当てた場合、user ロールのユーザーがログインすると、トークンには agent:all のみが含まれます。admin ロールのユーザーがログインすると、agent:all と admin:all の両方が含まれます。
:::
スコープの全一覧は認証ガイドを参照してください。
認証情報の確認
クライアント作成後、API 利用に必要な認証情報はアプリ詳細画面で確認できます。
Client ID
アプリ詳細画面の「技術設定」セクションに表示されます。コピーボタンでクリップボードにコピーできます。
Client Secret
Confidential クライアント（AC Confidential / CC）のみ。アプリ詳細画面に以下の操作ボタンがあります。
| 操作 | 説明 |
|---|---|
| 表示 | 目のアイコンをクリックすると、マスクされた Client Secret が表示されます。 |
| コピー | コピーアイコンをクリックすると、Client Secret をクリップボードにコピーできます。 |
| 再生成 | 更新アイコンをクリックすると、新しい Client Secret が生成されます。以前の Secret は即座に無効になります。 |
- Client Secret はパスワードと同等の機密情報です。安全に保管してください。
- ソースコードやバージョン管理システムにハードコードしないでください。環境変数や Secret Manager の利用を推奨します。
- Client Secret を再生成すると、旧 Secret を使用しているすべてのシステムで認証が失敗します。事前に影響範囲を確認してください。
- Public クライアント（AC Public）には Client Secret は発行されません。
次のステップ
認証情報を取得したら、以下のガイドに進んでください。
- クイックスタート — curl で API を体験する最短ルート
- 認証ガイド — AC / CC フローの詳細な手順
- API リファレンス — 全エンドポイントの仕様