認証ガイド

SaaS版の認証フロー（Authorization Code / Client Credentials）によるアクセストークン取得手順を解説します。

概要

AgenticStar SaaS版は OIDC（OpenID Connect）標準に準拠した認証を提供します。用途に応じて2つの認証フローを選択できます。

認証フロー

Authorization Code フロー エンドユーザー（人）がブラウザ経由でログインする場合に使用します。ユーザー認可画面を経由してアクセストークンと更新トークンを取得します。
Client Credentials フロー サーバー間通信など、ユーザーが関与しないシステム認証で使用します。クライアント認証情報のみでアクセストークンを取得します。

詳細仕様については、認証リファレンス（詳細仕様）をご参照ください。

前提条件

以下の準備が整っていることを確認してください。

Console（管理画面）でアプリケーション（クライアント）を登録済みであること
client_id と client_secret を取得済みであること
Authorization Code フローを使用する場合は、リダイレクトURI（redirect_uri）を登録済みであること

Authorization Code フロー

ユーザーがブラウザ経由でログインする場合の認証フローです。4つのステップで、アクセストークンと更新トークンを取得します。

ステップ 1: 認可リクエスト

ユーザーをブラウザで認可エンドポイントにリダイレクトします。ユーザーはログイン画面を経由して認可を行います。

GET /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: 登録済みのリダイレクトURI
state: CSRF 攻撃対策用のランダム値

ステップ 2: ユーザー認証

認可エンドポイントにアクセスすると、まずテナント選択画面が表示されます。テナントは、ご契約の AgenticStar 環境を識別するものです。テナントを選択すると、ご契約の AgenticStar 環境のログイン画面が表示されます。普段ご利用のアカウントと同じ認証方法でログインしてください。認証が完了すると、認可コードが発行されリダイレクト URI に返されます。

ステップ 3: 認可コード受け取り

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

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

注意

返された state がリクエスト時の値と一致することを確認してください（CSRF対策）
code は有効期限が短いため、すぐに次のステップでトークンに交換してください

ステップ 4: トークン取得

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

curl
# POST リクエスト例（curl）
curl -X POST https://auth.agenticstar.com/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: リクエスト時と同じURI
client_id: Console で取得したクライアントID
client_secret: Console で取得したクライアントシークレット（安全に保管してください）

レスポンス例

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid chat:all mcp:all"
}

注意

access_token は API リクエストの Authorization ヘッダーで使用します: Authorization: Bearer {access_token}
refresh_token は有効期限切れ時にトークンをリフレッシュするために保管してください

Client Credentials フロー

サーバー間通信など、ユーザーが関与しない場合の認証フローです。シンプルに認証情報のみでアクセストークンを取得します。

トークン取得リクエスト

クライアント認証情報を使用して直接アクセストークンを取得します。

curl
# POST リクエスト例（curl）
curl -X POST https://auth.agenticstar.com/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...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid chat:all"
}

リフレッシュトークンについて

Client Credentials フローではリフレッシュトークン（refresh_token）は発行されません。アクセストークンの有効期限切れ後は、同じリクエストを再度実行してください。

トークンリフレッシュ

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

curl
# POST リクエスト例（curl）
curl -X POST https://auth.agenticstar.com/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...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

ベストプラクティス

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

スコープ

スコープはアクセストークンに含まれる権限を表します。Console でクライアントに必要なスコープを割り当ててください。トークンには、クライアントに割り当てられたスコープのうち、ユーザーのロールで許可されたものが含まれます。

スコープ	説明
Chat
`chat:all`	チャット機能全般（以下すべてを含む）
`chat:exec`	チャット実行（開始・停止・リアルタイム応答・成果物取得）
`chat:history`	チャット履歴（会話一覧・削除）
`chat:file`	ファイル操作（アップロード・取得・削除）
MCP
`mcp:all`	MCP 機能全般（以下すべてを含む）
`mcp:exec`	MCP 実行
`mcp:file`	MCP ファイル添付
A2A
`a2a:all`	A2A 機能全般（以下すべてを含む）
`a2a:exec`	Agent-to-Agent 実行
`a2a:file`	A2A ファイル添付

概要​

前提条件​

Authorization Code フロー​

ステップ 1: 認可リクエスト​

ステップ 2: ユーザー認証​

ステップ 3: 認可コード受け取り​

ステップ 4: トークン取得​

Client Credentials フロー​

トークン取得リクエスト​

トークンリフレッシュ​

スコープ​

概要

前提条件

Authorization Code フロー

ステップ 1: 認可リクエスト

ステップ 2: ユーザー認証

ステップ 3: 認可コード受け取り

ステップ 4: トークン取得

Client Credentials フロー

トークン取得リクエスト

トークンリフレッシュ

スコープ