認証ガイド

AGENTIC STAR の認証フロー（OIDC 準拠）によるアクセストークン取得手順を解説します。

概要

AGENTIC STAR は OIDC（OpenID Connect）標準に準拠した認証を提供します。ご利用のエディションに応じて、適切な認証フローを選択してください。

	SaaS版 — アプリケーション	SaaS版 — システム連携	マーケットプレイス版
認証フロー	Authorization Code	Client Credentials	Client Credentials
用途	ユーザーがブラウザ経由でログイン	サーバー間のシステム連携（管理 API 等）	サーバー間のシステム認証
トークン取得	認可コードを経由して取得	クライアント認証情報で直接取得	クライアント認証情報で直接取得
リフレッシュトークン	あり	なし（期限切れ後に再取得）	なし（期限切れ後に再取得）
前提となる管理画面	Console	Console	Admin

詳細仕様については、各エディションの認証 API リファレンスをご参照ください。

SaaS版: 認証 API リファレンス（SaaS）
マーケットプレイス版: 認証 API リファレンス（MP）

Authorization Code フロー（SaaS版）

ユーザーがブラウザ経由でログインし、認可画面を経由してアクセストークンとリフレッシュトークンを取得する認証フローです。

前提条件

Console（管理画面）でアプリケーション（クライアント）を登録済みであること（Consoleガイド）
client_id と client_secret を取得済みであること
リダイレクト URI（redirect_uri）を登録済みであること

1. 認可リクエスト

ユーザーをブラウザで認可エンドポイントにリダイレクトします。

GET https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &state=STATE_VALUE

パラメータ

パラメータ	必須	説明
`response_type`	必須	`code` 固定
`client_id`	必須	Console で取得したクライアント ID
`redirect_uri`	必須	Console に登録済みのリダイレクト URI
`state`	推奨	CSRF 攻撃対策用のランダム値。指定した場合はレスポンスで返却されるため、リクエスト時の値と一致を必ず検証してください
`nonce`	—	ID Token のリプレイ攻撃対策用ランダム値（推奨）。指定すると ID Token の `nonce` クレームに同じ値が挿入されるため、検証して一致を確認してください
`ui_locales`	—	ログイン画面・同意画面の表示言語。`ja`（デフォルト）、`en`、`fr`、`es`、`th`、`id`、`ar` に対応

2. ユーザー認証

認可エンドポイントにアクセスすると、ログイン画面が表示されます。普段ご利用のアカウントと同じ認証方法でログインしてください。

同意画面が有効になっているアプリケーションの場合、初回利用時やスコープ追加時に同意画面が表示されます。内容を確認し、許可してください。

認証が完了すると、認可コードが発行されリダイレクト URI に返されます。

ログインできるアカウント

ログインには、ご契約の AGENTIC STAR 環境のアカウントが必要です。

アプリケーションの公開状態

公開状態（公開 / 非公開）によってアクセスできるユーザーが異なります。詳細は Consoleガイド — 公開設定を参照してください。

3. 認可コード受け取り

ユーザーが認可を許可すると、ブラウザは redirect_uri にリダイレクトされます。URL に一時的な認可コード（code）が含まれます。

https://yourapp.com/callback?
  code=AUTH_CODE_VALUE
  &state=STATE_VALUE

警告

state を指定した場合は、返された値がリクエスト時の値と一致することを必ず検証してください（CSRF 対策）
code は有効期限が短いため、すぐに次の Step でトークンに交換してください

4. トークンの取得

認可コードをアクセストークンに交換します。サーバー側で以下のリクエストを実行してください。

curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_VALUE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

パラメータ

grant_type: authorization_code 固定
code: 手順 3 で取得した認可コード
redirect_uri: 手順 1 と同じ URI
client_id: Console で取得したクライアント ID
client_secret: Console で取得したクライアントシークレット（安全に保管してください）

レスポンス例

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "scope": "openid chat:exec chat:history chat:file mcp:all"
}

トークンリフレッシュ

Authorization Code フローで取得したリフレッシュトークン（refresh_token）を使用して、新しいアクセストークンを取得できます。

curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN_VALUE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

レスポンス例

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "scope": "openid chat:exec chat:history chat:file mcp:all"
}

ベストプラクティス

アクセストークンの有効期限が切れる直前（例: 残り 5 分以内）にリフレッシュすることをお勧めします。これにより、API 呼び出し中のトークン有効期限切れエラーを防げます。

同意画面

Authorization Code フローでは、Console のアプリケーション設定で同意画面を有効にすると、ユーザーがアプリケーションにアクセス権限を許可するための同意画面が表示されます。

同意画面に表示される情報

アプリケーション名・ロゴ・説明
アプリケーションに許可するアクセス権限の一覧
サポート URL、プライバシーポリシー URL、利用規約 URL

アクセス権限について

アクセス権限は、アプリケーションが API で実行できる操作の範囲です。Console でアプリケーションに割り当てたスコープに基づき、権限の一覧が表示されます。基本的なユーザー情報（プロフィール、メールアドレス）へのアクセスは、OIDC 標準スコープとしてデフォルトで許可されます。

これらの情報は Console のアプリケーション設定で管理します。詳細は Consoleガイドを参照してください。

同意画面が表示されるタイミング

初回利用時 — ユーザーがそのアプリケーションを初めて利用する際に表示されます。ユーザーが同意すると、承認したスコープが記録されます。
スコープ追加時 — アプリケーションのスコープを後から追加した場合、次回認証時に同意画面が再度表示されます。このとき、新たに追加されたスコープだけでなく、既に承認済みのスコープも含めてすべてのスコープが表示されます。

一度同意したスコープは記録されるため、同じスコープ構成であれば 2 回目以降のログインでは同意画面は表示されません。

Client Credentials フロー

サーバー間のシステム認証に使用するフローです。ユーザーの介在なしに、クライアント認証情報のみでアクセストークンを取得します。SaaS版とマーケットプレイス版でエンドポイントが異なります。

SaaS版

前提条件

Console（管理画面）でシステム連携（クライアント）を登録済みであること（Consoleガイド — システム連携）
Client ID、Client Secret、Token URL を取得済みであること

トークンの取得

サーバー側で以下のリクエストを実行してください。

curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

パラメータ

grant_type: client_credentials 固定
client_id: Console で取得したクライアント ID
client_secret: Console で取得したクライアントシークレット

レスポンス例

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid users:read logs:read"
}

マーケットプレイス版

前提条件

マーケットプレイスで購入した AGENTIC STAR 環境のセットアップが完了していること
管理画面（Admin）でサービスアカウントを作成済みであること
以下の情報を取得済みであること:
- Client ID — サービスアカウントのクライアント ID
- Client Secret — サービスアカウントのシークレット（Admin 詳細画面で確認）

トークンの取得

サーバー側で以下のリクエストを実行してください。

curl
curl -X POST https://<your-domain>/api/v1/auth/external-service-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "<your-client-id>",
    "client_secret": "<your-client-secret>"
  }'

パラメータ

<your-domain>: ご利用環境のベース URL（例: api.example.com）
<your-client-id>: サービスアカウントのクライアント ID
<your-client-secret>: サービスアカウントのシークレット

レスポンス例

JSON
{
  "success": true,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 1800,
  "scope": "openid"
}

トークンの再取得

Client Credentials フローではリフレッシュトークンは発行されません。アクセストークンの有効期限（expires_in に指定された秒数）が切れた場合は、同じリクエストを再度実行して新しいトークンを取得してください。

ベストプラクティス

有効期限を管理し、期限切れ前に新しいトークンを取得することで、API 呼び出しの中断を防げます。

スコープ

スコープは、アクセストークンに含まれる権限を表します。アプリケーションが API で実行できる操作は、付与されたスコープによって決まります。

スコープの割り当て

SaaS版: Console でクライアント作成時にスコープを選択します。アプリケーション（AC フロー）では Chat API・MCP・A2A 用スコープを、システム連携（CC フロー）では管理 API 用スコープを選択します（Consoleガイド）。割り当てたスコープに応じて、利用可能な API が制限されます。
マーケットプレイス版: スコープによる制限はありません。すべての API を利用できます。

スコープ一覧

AGENTIC STAR のエージェントには、Chat API（SSE）、MCP、A2A の 3 つの接続方式があります。利用する接続方式に応じたスコープが必要です。接続方式の詳細は接続方式ガイドを参照してください。

Chat API（SSE）で接続する場合

スコープ	説明
`chat:exec`	チャットの開始・停止、ストリーミング応答の受信、成果物の取得。Chat API を利用する場合は必須です。
`chat:history`	会話一覧・メッセージ履歴の取得（アクティブ / アーカイブ）、会話の削除・タイトル更新・アーカイブ済み会話の復元、メッセージ検索。
`chat:file`	チャットで使用するファイルのアップロード・取得・削除。

MCP / A2A で接続する場合

スコープ	説明
`mcp:all`	MCP（Model Context Protocol）でエージェントに接続する場合に必要です。
`a2a:all`	A2A（Agent-to-Agent）プロトコルでエージェントに接続する場合に必要です。

管理 API を利用する場合

スコープ	説明
`sharedmemory:query`	共有メモリの検索。
`users:read`	ユーザー情報の読み取り（一覧・詳細）。
`users:manage`	ユーザーの管理操作（承認・承認取り消し・削除・ロール変更）。`users:read` の権限を含みます。
`logs:read`	ログの閲覧（監査ログ・LLMログ・アクセスログ）。
`master:manage`	マスターデータの管理（部署・職種の作成・更新・削除）。

スコープの選択指針

アプリケーション（AC フロー）で選択可能なスコープ

Chat API でエージェントを利用する場合: chat:exec は必須です。履歴管理やファイル操作が必要であれば chat:history、chat:file を追加してください。
MCP 対応 AI エージェントから接続する場合: mcp:all を選択してください。
A2A 対応 AI エージェントから接続する場合: a2a:all を選択してください。
複数の接続方式を併用する場合は、それぞれのスコープを組み合わせて選択できます。

システム連携（CC フロー）で選択可能なスコープ

管理 API を利用する場合: 必要な操作に応じて users:read、users:manage、logs:read、master:manage、sharedmemory:query 等を選択してください。

アクセストークンの利用

取得したアクセストークンは、API リクエストの Authorization ヘッダーに Bearer トークンとして設定してください。

Authorization: Bearer <access_token>

すべての API エンドポイントで同じ形式を使用します。詳細はユーザー API リファレンスを参照してください。

概要​

Authorization Code フロー（SaaS版）​

前提条件​

1. 認可リクエスト​

2. ユーザー認証​

3. 認可コード受け取り​

4. トークンの取得​

トークンリフレッシュ​

同意画面​

同意画面に表示される情報​

同意画面が表示されるタイミング​

Client Credentials フロー​

SaaS版​

前提条件​

トークンの取得​

マーケットプレイス版​

前提条件​

トークンの取得​

トークンの再取得​

スコープ​

スコープの割り当て​

スコープ一覧​

Chat API（SSE）で接続する場合​

MCP / A2A で接続する場合​

管理 API を利用する場合​

スコープの選択指針​

アプリケーション（AC フロー）で選択可能なスコープ​

システム連携（CC フロー）で選択可能なスコープ​

アクセストークンの利用​

概要

Authorization Code フロー（SaaS版）

前提条件

1. 認可リクエスト

2. ユーザー認証

3. 認可コード受け取り

4. トークンの取得

トークンリフレッシュ

同意画面

同意画面に表示される情報

同意画面が表示されるタイミング

Client Credentials フロー

SaaS版

前提条件

トークンの取得

マーケットプレイス版

前提条件

トークンの取得

トークンの再取得

スコープ

スコープの割り当て

スコープ一覧

Chat API（SSE）で接続する場合

MCP / A2A で接続する場合

管理 API を利用する場合

スコープの選択指針

アプリケーション（AC フロー）で選択可能なスコープ

システム連携（CC フロー）で選択可能なスコープ

アクセストークンの利用