# Consoleガイド

Console は、API のクライアントと LLM Gateway のキーを管理する画面です。管理コンソールとは別の画面です（[管理コンソール リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/admin/reference/admin-ref.md#%E8%A1%A8%E8%A8%98)）。

このガイドでは、Console でアプリケーションまたはシステム連携を作成し、API 利用に必要な認証情報とスコープを設定する手順を解説します。

<!-- -->

## 概要

AGENTIC STAR の API を利用するには、Console で利用目的に応じたクライアントを事前に作成する必要があります。

|              | アプリケーション                | システム連携                 |
| ------------ | ----------------------- | ---------------------- |
| 用途           | ユーザーがログインして利用するアプリケーション | サーバー間の連携（システム連携 API 等） |
| 認証フロー        | Authorization Code      | Client Credentials     |
| ユーザー認証       | あり（ブラウザ経由のログイン）         | なし（クライアント認証情報のみ）       |
| Console メニュー | 「アプリ一覧」                 | 「システム連携」               |

> **前提条件**
>
> - Console にログインできること（developer ロール以上）
> - 組織の管理者から API 利用の許可を得ていること
>
> 詳細は[認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/auth-guide.md)を参照してください。

## アプリケーションの作成手順

Console の「アプリ一覧」メニューから「新規作成」をクリックして作成を開始します。

### 1. アプリケーションの種類の選択

利用用途に応じてアプリケーションの種類を選択します。種類によって認証方式やセキュリティ設定が自動的に決定されます。**作成後に種類は変更できません。**

|                   | Web アプリケーション                   | SPA                                | モバイル / ネイティブ                      |
| ----------------- | ------------------------------ | ---------------------------------- | --------------------------------- |
| 用途                | サーバーサイドで動作する Web アプリケーション      | ブラウザ上で動作する Single Page Application | モバイルアプリやデスクトップアプリ                 |
| クライアントタイプ         | Confidential（Client Secret あり） | Public（Client Secret なし、PKCE で認証）  | Public（Client Secret なし、PKCE で認証） |
| 認証フロー             | Authorization Code             | Authorization Code + PKCE（必須）      | Authorization Code + PKCE（必須）     |
| Redirect URI      | 必須                             | 必須                                 | 必須                                |
| Web Origins（CORS） | 任意                             | 必須                                 | —                                 |

> **SPA / モバイルアプリの場合**
>
> SPA およびモバイルアプリは Public Client として設定されます。PKCE（S256）が必須となり、`code_challenge` / `code_verifier` によるチャレンジ検証で保護されます。S256 以外の方式（plain 等）には対応していません。

### 2. 基本情報の入力

| 項目            | 必須 | 説明                                                         |
| ------------- | -- | ---------------------------------------------------------- |
| アプリ名          | ✓  | アプリケーションの表示名（最大255文字）。認可画面にも表示されます。                        |
| ロゴ            | ✓  | アプリケーションのロゴ画像（PNG, JPEG, SVG 形式、500KB 以下、推奨 128x128px 以上）。 |
| 短い説明          | ✓  | 50文字以内の簡潔な説明。アプリ一覧に表示されます。                                 |
| 詳細説明          | ✓  | アプリケーションの詳細な説明（最大10,000文字）。                                |
| サポートURL       |    | サポートページの URL。同意画面に表示されます。                                  |
| プライバシーポリシーURL |    | プライバシーポリシーの URL。同意画面に表示されます。                               |
| 利用規約URL       |    | 利用規約の URL。同意画面に表示されます。                                     |

### 3. 技術設定

| 項目                | 必須 | 説明                                                                                                                                |
| ----------------- | -- | --------------------------------------------------------------------------------------------------------------------------------- |
| Client ID         | —  | 自動生成される UUID です。変更はできません。作成後にコピーして利用します。                                                                                          |
| Redirect URI      | ✓  | 認可完了後のリダイレクト先 URL を1つ以上登録します。完全一致で検証されるため、正確な URL を入力してください。                                                                      |
| Web Origins（CORS） | ※  | SPA の場合のみ必須。ブラウザからの直接 API 呼び出しを許可するオリジン URL を登録します。Web アプリケーションの場合は任意で、未入力のときは登録した Redirect URI のオリジンが自動的に許可されます。モバイルの場合は表示されません。 |

> **Redirect URI の登録について**
>
> Redirect URI はセキュリティ上、完全一致で検証されます。開発環境用（`http://localhost:3000/callback`）と本番環境用（`https://yourapp.com/callback`）の両方を登録しておくことをお勧めします。ワイルドカードは使用できません。

### 4. スコープの選択

アプリケーションが利用する機能に応じて、必要なスコープを選択します。選択したスコープが、このアプリケーションで利用可能な権限の最大範囲になります。

利用可能なスコープの一覧と選択指針については、[認証ガイド — スコープ](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/auth-guide.md#%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%97)を参照してください。

> **書き込み・削除・判断のスコープ**
>
> `project:write`・`project:delete`・`project:decide` を選ぶと `project:read` も、`assets:write`・`assets:delete` を選ぶと `assets:read` も選ばれます。閲覧のスコープ（`project:read`・`assets:read`）を外すと、同じ領域の書き込み・削除・判断のスコープも外れます。

### 5. 公開範囲

アプリケーションを使える人を、「テナントの全員が使える」のスイッチで切り替えます。

| スイッチ   | 使える人                         |
| ------ | ---------------------------- |
| オフ（既定） | 管理者と開発者だけです。開発中はオフのままを推奨します。 |
| オン     | このテナントの全ユーザーです。              |

### 6. 同意画面

同意画面を有効にするかどうかを設定します。有効にすると、基本情報で設定したアプリケーション名・ロゴ・説明、サポート URL、プライバシーポリシー URL、利用規約 URL が同意画面に反映されます。同意画面を有効にする場合は、これらを正確に入力してください。

同意画面の挙動（表示タイミング・表示される情報）については、[認証ガイド — 同意画面](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/auth-guide.md#%E5%90%8C%E6%84%8F%E7%94%BB%E9%9D%A2)を参照してください。

### 7. 作成の完了

「作成」ボタンをクリックすると、アプリケーションが作成されます。作成完了後、アプリ詳細画面に遷移します。ここで Client ID と Client Secret を確認できます。

## システム連携の作成手順

システム連携 API をサーバー間で利用する場合は、「システム連携」メニューから Client Credentials クライアントを作成します。ユーザーのログインは不要で、クライアント認証情報のみでアクセストークンを取得します。

Console の「システム連携」メニューから「新規作成」をクリックして作成を開始します。

### 1. 基本情報の入力

| 項目 | 必須 | 説明                |
| -- | -- | ----------------- |
| 名前 | ✓  | 連携先の表示名（最大255文字）。 |
| 説明 |    | 連携の用途や目的の説明。      |

### 2. スコープの選択

利用するシステム連携 API に応じて、必要なスコープを選択します。

利用可能なスコープの一覧は、[認証ガイド — スコープ](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/auth-guide.md#%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%97)を参照してください。MCP からシステム連携を使う場合は、`mcp:connect` もあわせて選択します（[AI クライアント接続ガイド（MCP）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/ai-client-guide.md)）。

> **書き込みスコープの選択**
>
> `users:manage` や `master:manage` 等の書き込みスコープは、データの変更・削除を伴います。必要最小限のスコープを選択してください。

### 3. プロジェクト制限の設定

`project:read`・`project:run` のいずれかを選択した場合は、この連携が操作できるプロジェクトの範囲を設定します。

| 設定               | 説明                                                                     |
| ---------------- | ---------------------------------------------------------------------- |
| 指定したプロジェクトのみ     | 操作させたいプロジェクトの ID を、1 行に 1 つ入力します。入力したプロジェクトだけを操作できます。最大 100 件まで入力できます。 |
| テナント内のすべてのプロジェクト | テナント内のすべてのプロジェクトを操作できます。今後作成されるプロジェクトも対象になります。                         |

> **プロジェクト制限は必須です**
>
> プロジェクト制限を設定しないまま `project:*` 系のスコープを付与しても、**プロジェクト API はすべて `403 Forbidden` になります**。未設定は「テナント内のすべてのプロジェクト」として扱われません。
>
> 範囲外のプロジェクト ID を指定した場合は、存在しない場合と同じ `404 Not Found` が返ります。設定を変更した場合、次に取得したアクセストークンから反映されます。

プロジェクト API の仕様は[システム連携 API リファレンス — プロジェクト](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/admin-api-reference.md#projects)を参照してください。

### 4. 作成の完了

「作成」ボタンをクリックすると、システム連携が作成されます。作成完了後、詳細画面に遷移します。ここで Client ID、Client Secret、Token URL を確認できます。

## 認証情報の確認

クライアント作成後、API 利用に必要な認証情報は詳細画面で確認できます。

### アプリケーションの認証情報

アプリ詳細画面で以下の情報を確認できます。

- **Client ID** — 「技術設定」セクションに表示されます。コピーボタンでクリップボードにコピーできます。
- **Client Secret** — Web アプリケーション（Confidential）の場合に発行されます。

| 操作  | 説明                                                               |
| --- | ---------------------------------------------------------------- |
| 表示  | 目のアイコンをクリックすると、マスクされた Client Secret が表示されます。                     |
| コピー | コピーアイコンをクリックすると、Client Secret をクリップボードにコピーできます。                  |
| 再生成 | 更新アイコンをクリックすると、新しい Client Secret が生成されます。以前の Secret は即座に無効になります。 |

### システム連携の認証情報

システム連携の詳細画面で以下の情報を確認できます。

- **Client ID** — コピーボタンでクリップボードにコピーできます。
- **Client Secret** — 表示・コピー・再生成が可能です（アプリケーションと同じ操作）。
- **Token URL** — アクセストークン取得先の URL です。コピーボタンでクリップボードにコピーできます。
- **API キー** — 固定の API キーを発行・再発行・削除できます（下の「API キー」）。

> **Client Secret の取り扱い**
>
> - Client Secret はパスワードと同等の機密情報です。安全に保管してください。
> - ソースコードやバージョン管理システムにハードコードしないでください。環境変数や Secret Manager の利用を推奨します。
> - Client Secret を再生成すると、旧 Secret を使用しているすべてのシステムで認証が失敗します。事前に影響範囲を確認してください。

### API キー

システム連携の詳細画面で、固定の API キー（`agtstr_…`）を発行できます。API キーを `Authorization: Bearer agtstr_…` で送ると、そのまま API と MCP を呼べます。トークンを取り直す必要はありません。`x-api-key` のヘッダーでは送れません。

| 操作  | 画面のボタン     | 結果                                                        |
| --- | ---------- | --------------------------------------------------------- |
| 発行  | API キーを発行  | 新しい API キーが表示されます。                                        |
| 再発行 | API キーを再発行 | 新しい API キーが表示され、前の API キーは使えなくなります。連携先の設定を新しいキーに更新してください。 |
| 削除  | API キーを削除  | その API キーでのアクセスが止まります。削除は取り消せません。                         |

- 再発行と削除は、反映まで最大 1 分ほどかかります。
- API キーの値を後から見られるのは、組織の管理者と開発者です。プロジェクトオーナーには、発行と再発行の直後にだけ表示されます。控え忘れたときは再発行してください。プロジェクトオーナーが作ったシステム連携の API キーは、管理者にも表示されません。
- API キーは、Client Secret と同じく機密情報として扱ってください。

### 資格情報が漏れたとき

アプリケーションやシステム連携の資格情報が漏れたときは、次のように止めます。

**アプリケーション**（人がログインして使うもの）は、漏れたものごとに次のように止めます。

| 漏れたもの                       | 止め方                                                                                      |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| Client Secret（Web アプリケーション） | Client Secret を再生成するか、アプリケーションを削除します。再生成すると、以前の Secret でのトークンの取得はすぐにできなくなります。            |
| 利用者のトークン、またはアプリケーションそのもの    | アプリケーションを削除します。新しいログインとトークンの更新は、すぐにできなくなります。削除は取り消せません。このアプリケーションを導入しているほかの企業でも使えなくなります。 |

- アプリケーションの削除と Client Secret の再生成ができるのは、アプリケーションを作った組織の管理者と開発者です。SPA とモバイル / ネイティブのアプリケーションには Client Secret が無いので、削除で止めます。
- 「テナントの全員が使える」を切り替えても、発行済みのトークンは止まりません。変わるのは、アプリケーションにアクセスできるユーザーです。
- 利用者 1 人のセッションだけを切る操作は、Console にはありません。

**システム連携**は、漏れたものごとに次のように止めます。

| 漏れたもの         | 止め方                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------ |
| Client Secret | Client Secret を再生成するか、システム連携を無効化します。再生成すると、以前の Secret でのトークンの取得はすぐにできなくなります。               |
| API キー        | その API キーを削除するか、システム連携を無効化します。Client Secret を再生成しても、API キーでのアクセスは止まりません。反映まで最大 1 分ほどかかります。 |

- 発行済みのアクセストークンは、アプリケーションを削除しても、システム連携を無効化しても、有効期限（1 時間）まで使える場合があります。
- プロジェクトオーナーが管理する連携では、Client Secret の再生成と API キーの削除はプロジェクトオーナーが行います。管理者ができるのは、無効化と削除だけで、無効化した連携を再び有効にすることはできません。
- 漏れた資格情報でできるのは、そのシステム連携に付けたスコープの範囲の操作です。たとえばプロジェクトのスコープなら、プロジェクト制限の範囲のプロジェクトの一覧と実行状況の参照、実行の開始と中断、トリガーの発火です（外部のサービスに書き込むエージェントなら、外部にも影響が出ます）。すでに読まれたデータは取り戻せません。

## 次のステップ

認証情報を取得したら、利用目的に応じて以下のガイドに進んでください。

- [クイックスタート](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/quickstart/call-api.md) — curl で API を体験する最短ルート
- [認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/auth-guide.md) — 認証フローの詳細な手順
- [ユーザー API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md) — ユーザー向け API 全エンドポイントの仕様
