認証リファレンス（SaaS版）

AgenticStar SaaS版の OIDC エンドポイント仕様、JWT クレーム構造、スコープ、エラーコードのリファレンスです。

エンドポイント一覧

メソッド	エンドポイント	説明
GET	`/.well-known/openid-configuration`	OpenID Connect Discovery エンドポイント
GET	`/auth/v1/authorize`	Authorization Code フローのユーザー認可エンドポイント
POST	`/auth/v1/token`	トークン取得エンドポイント（AC / CC / Refresh Token フロー対応）
GET	`/auth/v1/userinfo`	ユーザー情報取得エンドポイント
GET	`/auth/v1/jwks`	公開鍵セット（JWKS）エンドポイント
POST	`/auth/v1/revoke`	トークン失効エンドポイント
GET	`/auth/v1/logout`	ログアウトエンドポイント

ベース URL: https://auth.agenticstar.jp/federation

Issuer: https://auth.agenticstar.jp/realms/federation

Discovery

GET /.well-known/openid-configuration

OpenID Connect Discovery エンドポイント。クライアントが必要なエンドポイント URL やサーバー情報を取得します。

リクエスト例

curl
curl https://auth.agenticstar.jp/federation/.well-known/openid-configuration

レスポンス例

JSON
{
  "issuer": "https://auth.agenticstar.jp/realms/federation",
  "authorization_endpoint": "https://auth.agenticstar.jp/federation/auth/v1/authorize",
  "token_endpoint": "https://auth.agenticstar.jp/federation/auth/v1/token",
  "userinfo_endpoint": "https://auth.agenticstar.jp/federation/auth/v1/userinfo",
  "jwks_uri": "https://auth.agenticstar.jp/federation/auth/v1/jwks",
  "revocation_endpoint": "https://auth.agenticstar.jp/federation/auth/v1/revoke",
  "end_session_endpoint": "https://auth.agenticstar.jp/federation/auth/v1/logout",
  "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
  "response_types_supported": ["code"],
  "response_modes_supported": ["query"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
  "code_challenge_methods_supported": ["S256"]
}

Authorization Code フロー

GET /auth/v1/authorize

ユーザーが認証してアプリケーションを認可し、Authorization Code を取得します。ウェブブラウザで直接アクセスしてください。

クエリパラメータ

パラメータ	型	必須	説明
`client_id`	`string`	必須	クライアントID
`redirect_uri`	`string`	必須	認可後にリダイレクトするURI（事前登録が必要）
`response_type`	`string`	必須	code を指定してください
`scope`	`string`	必須	スペース区切りのスコープ。openid は必須
`state`	`string`	必須	CSRF 対策用。クライアントが生成した予測不可能な値
`nonce`	`string`	—	ID Token への nonce クレーム挿入用（推奨）
`kc_idp_hint`	`string`	—	テナント ID ヒント。ログイン画面をスキップできます

リクエスト URL 例

curl
https://auth.agenticstar.jp/federation/auth/v1/authorize?\
  client_id=my-client&\
  redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&\
  response_type=code&\
  scope=openid%20chat%3Aall&\
  state=abc123xyz&\
  nonce=xyz789abc

成功時

ユーザーが認可に成功した場合、以下の形式でリダイレクトされます：

https://app.example.com/callback?\
  code=AUTH_CODE&\
  state=abc123xyz

エラー時

エラーが発生した場合、以下の形式でリダイレクトされます：

https://app.example.com/callback?\
  error=invalid_scope&\
  error_description=...&\
  state=abc123xyz

エラーコード	説明
`invalid_request`	必須パラメータが不足している、または形式が不正
`unauthorized_client`	クライアントが認可フローを使用する権限がない
`invalid_scope`	リクエストされたスコープが無効または不足
`server_error`	サーバー側のエラー

Token エンドポイント

POST /auth/v1/token

Authorization Code または Client Credentials フローでアクセストークン（および ID Token）を取得します。

リクエストヘッダー

ヘッダー	必須	説明
`Content-Type`	必須	`application/x-www-form-urlencoded`

Authorization Code フロー

リクエストボディ

パラメータ	型	必須	説明
`grant_type`	`string`	必須	authorization_code を指定
`code`	`string`	必須	Authorization Code エンドポイントから取得した認可コード
`redirect_uri`	`string`	必須	Authorization Code 要求時に指定した redirect_uri と同一値
`client_id`	`string`	必須	クライアントID
`client_secret`	`string`	必須	クライアントシークレット（バックエンド間通信で安全に送信してください）

リクエスト例

curl
curl -X POST https://auth.agenticstar.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-client" \
  -d "client_secret=my-secret"

Client Credentials フロー

リクエストボディ

パラメータ	型	必須	説明
`grant_type`	`string`	必須	client_credentials を指定
`client_id`	`string`	必須	クライアントID
`client_secret`	`string`	必須	クライアントシークレット

サービスアカウント機能が有効な場合、クライアントに紐づけられたテナント情報がトークンに含まれます。

リクエスト例

curl
curl -X POST https://auth.agenticstar.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=my-client" \
  -d "client_secret=my-secret"

成功時（200 OK）

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "scope": "openid chat:all"
}

エラーレスポンス

ステータス	エラーコード	説明
400	`invalid_request`	必須パラメータが不足、または形式が不正
401	`invalid_client`	クライアント認証に失敗（ID / Secret が不正）
400	`invalid_grant`	Authorization Code が無効、または有効期限切れ
400	`invalid_scope`	リクエストされたスコープが無効

Refresh Token

POST /auth/v1/token (refresh_token grant)

Refresh Token を使用してアクセストークンを更新します。

リクエストボディ

パラメータ	型	必須	説明
`grant_type`	`string`	必須	refresh_token を指定
`refresh_token`	`string`	必須	Token エンドポイントから取得した Refresh Token
`client_id`	`string`	必須	クライアントID
`client_secret`	`string`	必須	クライアントシークレット

リクエスト例

curl
curl -X POST https://auth.agenticstar.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=my-client" \
  -d "client_secret=my-secret"

レスポンス例

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "scope": "openid chat:all"
}

UserInfo

GET /auth/v1/userinfo

有効なアクセストークンを使用してユーザー情報を取得します。テナント経由の認証の場合、OIDC 標準クレームに加えて idp ブロックに IdP のユーザー情報が含まれます。

リクエストヘッダー

ヘッダー	必須	説明
`Authorization`	必須	`Bearer <access_token>`

リクエスト例

curl
curl https://auth.agenticstar.jp/federation/auth/v1/userinfo \
  -H "Authorization: Bearer <access_token>"

レスポンスフィールド

フィールド	型	説明
`sub`	`string`	ユーザー ID（OIDC 標準）
`idp`	`object`	IdP から取得したユーザー情報（テナント経由の場合のみ）
`idp.sub`	`string`	IdP 側のユーザー ID
`idp.name`	`string`	表示名
`idp.preferred_username`	`string`	ユーザー名（メールアドレス）
`idp.email`	`string`	メールアドレス
`idp.email_verified`	`boolean`	メールアドレスが検証済みか
`idp.organization`	`object`	所属組織（id と label を含む）
`idp.job`	`object`	役職（id と label を含む）
`idp.bio`	`string`	自己紹介

レスポンス例

JSON
{
  "sub": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "idp": {
    "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "yamada_taro",
    "preferred_username": "taro.yamada@example.com",
    "email": "taro.yamada@example.com",
    "email_verified": true,
    "organization": {
      "id": "org-001",
      "label": "Example Corp."
    },
    "job": {
      "id": "job-001",
      "label": "Engineer"
    },
    "bio": "Software engineer"
  }
}

エラーレスポンス

ステータス	エラーコード	説明
401	`invalid_token`	トークンが無効または有効期限切れ
502	`bad_gateway`	IdP からのユーザー情報取得に失敗

JWKS

GET /auth/v1/jwks

JWT 署名検証用の公開鍵セット（JWKS）を取得します。ID Token や Access Token の署名検証に使用してください。

リクエスト例

curl
curl https://auth.agenticstar.jp/federation/auth/v1/jwks

レスポンス例

JSON
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-id-1",
      "use": "sig",
      "n": "modulus...",
      "e": "AQAB"
    }
  ]
}

Revoke

POST /auth/v1/revoke

アクセストークンや Refresh Token を失効させます。

リクエストヘッダー

ヘッダー	必須	説明
`Content-Type`	必須	`application/x-www-form-urlencoded`

リクエストボディ

パラメータ	型	必須	説明
`token`	`string`	必須	失効させるトークン（Access Token または Refresh Token）
`client_id`	`string`	必須	クライアントID
`client_secret`	`string`	必須	クライアントシークレット

リクエスト例

curl
curl -X POST https://auth.agenticstar.jp/federation/auth/v1/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_TOKEN" \
  -d "client_id=my-client" \
  -d "client_secret=my-secret"

成功時は 204 No Content が返されます。

Logout

GET /auth/v1/logout

RP-Initiated Logout エンドポイント。ユーザーセッションを終了し、指定の URI にリダイレクトします。ウェブブラウザで直接アクセスしてください。ログアウト確認画面が表示されます。

クエリパラメータ

パラメータ	型	必須	説明
`id_token_hint`	`string`	推奨	ID Token。クライアントの特定に使用されます（JWT の azp クレームから client_id を抽出）。client_id パラメータが指定されていない場合に必要です。
`client_id`	`string`	—	クライアント ID。id_token_hint の代わりにクライアントを直接指定できます。両方指定した場合はこちらが優先されます。
`post_logout_redirect_uri`	`string`	—	ログアウト後にリダイレクトする URI（事前登録が必要）
`logout_hint`	`string`	—	ログアウト対象のヒント情報
`state`	`string`	—	リダイレクト時に返却される状態パラメータ
`ui_locales`	`string`	—	ログアウト画面の表示言語（例: ja）

備考

id_token_hint または client_id のいずれかでクライアントを特定する必要があります。どちらも指定されていない場合、エラーページにリダイレクトされます。

リクエスト URL 例

https://auth.agenticstar.jp/federation/auth/v1/logout?\
  id_token_hint=eyJhbGciOiJSUzI1NiJ9...&\
  post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2F&\
  state=abc123

JWT 仕様

ID Token および Access Token は JWT 形式で発行されます。JWT は署名済み（署名アルゴリズム: RS256）で、header.payload.signature の3部から構成されています。

JWT 構造

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLWlk....signature_part

JSON
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-1"
}

Payload（クレーム）

以下のセクションで詳細なクレーム一覧を参照してください。

クレーム一覧

標準クレーム

クレーム	型	説明
`sub`	`string`	サブジェクト ID。認証基盤内でユーザーまたはサービスアカウントを一意に識別する UUID
`iss`	`string`	Issuer。トークン発行元（https://auth.agenticstar.jp/federation）
`aud`	`string`	Audience。トークンの対象（クライアント ID）
`exp`	`number`	有効期限（Unix タイムスタンプ）
`iat`	`number`	発行日時（Unix タイムスタンプ）
`azp`	`string`	Authorized Party。トークンを要求したクライアント ID
`scope`	`string`	付与されたスコープ（スペース区切り）

テナント情報（`tenant.*`）

テナント（企業 / SaaS）に関する情報です。Access Token および ID Token にネスト構造で含まれます。

クレーム	型	説明	トークン
`tenant.id`	`string`	テナント ID	AT / IDT
`tenant.type`	`string`	enterprise または saas	AT / IDT
`tenant.endpoint`	`string`	テナントのエンドポイント URL	AT / IDT

IdP プロフィール（`idp.*`）

IdP（企業認証基盤）から取得したユーザー情報です。ネスト構造で含まれます。CC フローでリンクユーザーが設定されている場合も同じ構造で出力されます。

クレーム	型	説明	トークン
`idp.sub`	`string`	IdP ユーザー ID	AT / IDT
`idp.preferred_username`	`string`	IdP ユーザー名（メールアドレス）	AT / IDT
`idp.display_name`	`string`	表示名	IDT
`idp.email`	`string`	メールアドレス	IDT
`idp.organization`	`string`	所属組織	AT / IDT
`idp.job`	`string`	役職	AT / IDT
`idp.bio`	`string`	自己紹介	AT / IDT

ロール

クレーム	型	説明
`realm_access.roles`	`string[]`	ユーザーに付与されたロール（例: user, admin, developer）

JWT Access Token Payload 例

JSON
{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "iss": "https://auth.agenticstar.jp/federation",
  "aud": "my-client",
  "exp": 1704070800,
  "iat": 1704067200,
  "azp": "my-client",
  "scope": "openid chat:all",
  "tenant": {
    "id": "enterprise-a",
    "type": "enterprise",
    "endpoint": "https://enterprise-a.example.com"
  },
  "idp": {
    "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "preferred_username": "user@enterprise-a.com",
    "organization": "Enterprise A Corp.",
    "job": "Engineer",
    "bio": "Software developer"
  },
  "realm_access": {
    "roles": ["user"]
  }
}

スコープ

スコープ一覧

以下は主要なスコープです。全一覧は API リファレンスを参照してください。

Chat API

chat:exec - チャット実行
chat:history - チャット履歴閲覧・削除
chat:file - ファイル操作
chat:all - すべての chat スコープ

MCP / A2A

mcp:exec - MCP 経由のタスク実行
a2a:exec - A2A 経由のタスク実行

スコープ制御の仕組み

Console でクライアントにスコープを割り当てることで、トークンに含まれるスコープが決定されます。ユーザーのロールで許可されたスコープのみがトークンに付与されます。

スコープ割り当てフロー

Console の Client Scope Role Mapping でクライアントにスコープを割り当てます。トークン生成時、以下の条件で実際に付与されるスコープが決定されます：

クライアントに割り当てられたスコープ
ユーザーのロール（user, admin, developer など）が許可するスコープの交集合
結果として、ユーザーのロール範囲内の必要なスコープのみがトークンに含まれます

エラーコード

OAuth 2.0 / OIDC エラー

エラーコード	説明	対応方法
`invalid_request`	必須パラメータが不足、または形式が不正	リクエストパラメータを確認してください
`unauthorized_client`	クライアントに権限がない、またはクライアント ID が不正	クライアント ID と設定を確認してください
`invalid_client`	クライアント認証に失敗（ID / Secret が不正）	クライアント ID とシークレットを確認してください
`invalid_grant`	Authorization Code が無効、有効期限切れ、または既に使用済み	Authorization Code を再取得してください
`invalid_scope`	リクエストされたスコープが無効、または未割	Console でクライアントにスコープを割り当ててください
`server_error`	認証基盤との通信エラーなど、サーバー側のエラー	しばらく待ってから再度お試しください。問題が続く場合はサポートに連絡してください
`invalid_token`	トークンが無効または有効期限切れ	新しいトークンを取得してください

HTTP ステータスコード

ステータス	説明
`200 OK`	リクエストが成功
`204 No Content`	リクエストが成功（レスポンスボディなし）
`302 Found`	リダイレクト（Authorization / Logout エンドポイント）
`400 Bad Request`	リクエストが不正
`401 Unauthorized`	認証に失敗、またはトークンが無効
`403 Forbidden`	リクエストが禁止されている
`500 Internal Server Error`	サーバー内部エラー

エンドポイント一覧​

Discovery​

リクエスト例​

レスポンス例​

Authorization Code フロー​

クエリパラメータ​

リクエスト URL 例​

成功時​

エラー時​

Token エンドポイント​

リクエストヘッダー​

Authorization Code フロー​

リクエストボディ​

リクエスト例​

Client Credentials フロー​

リクエストボディ​

リクエスト例​

成功時（200 OK）​

エラーレスポンス​

Refresh Token​

リクエストボディ​

リクエスト例​

レスポンス例​

UserInfo​

リクエストヘッダー​

リクエスト例​

レスポンスフィールド​

レスポンス例​

エラーレスポンス​

JWKS​

リクエスト例​

レスポンス例​

Revoke​

リクエストヘッダー​

リクエストボディ​

リクエスト例​

Logout​

クエリパラメータ​

リクエスト URL 例​

JWT 仕様​

JWT 構造​

Header​

Payload（クレーム）​

クレーム一覧​

標準クレーム​

テナント情報（tenant.*）​

IdP プロフィール（idp.*）​

ロール​

JWT Access Token Payload 例​

スコープ​

スコープ一覧​

スコープ制御の仕組み​

スコープ割り当てフロー​

エラーコード​

OAuth 2.0 / OIDC エラー​

HTTP ステータスコード​

エンドポイント一覧

Discovery

リクエスト例

レスポンス例

Authorization Code フロー

クエリパラメータ

リクエスト URL 例

成功時

エラー時

Token エンドポイント

リクエストヘッダー

Authorization Code フロー

リクエストボディ

リクエスト例

Client Credentials フロー

リクエストボディ

リクエスト例

成功時（200 OK）

エラーレスポンス

Refresh Token

リクエストボディ

リクエスト例

レスポンス例

UserInfo

リクエストヘッダー

リクエスト例

レスポンスフィールド

レスポンス例

エラーレスポンス

JWKS

リクエスト例

レスポンス例

Revoke

リクエストヘッダー

リクエストボディ

リクエスト例

Logout

クエリパラメータ

リクエスト URL 例

JWT 仕様

JWT 構造

Header

Payload（クレーム）

クレーム一覧

標準クレーム

テナント情報（`tenant.*`）

IdP プロフィール（`idp.*`）

ロール

JWT Access Token Payload 例

スコープ

スコープ一覧

スコープ制御の仕組み

スコープ割り当てフロー

エラーコード

OAuth 2.0 / OIDC エラー

HTTP ステータスコード