メインコンテンツまでスキップ

認証 API リファレンス（MP）

マーケットプレイス版の認証エンドポイント仕様、JWT クレーム構造、エラーコードのリファレンスです。

認証エンドポイント一覧​

Marketplace

マーケットプレイス版は Client Credentials フローに対応した認証エンドポイントを提供します。サービスアカウントの認証情報でアクセストークンを取得し、API を利用します。

メソッドエンドポイント説明
POST/api/v1/auth/external-service-tokenトークンエンドポイント。Client Credentials フローでアクセストークンを発行します。
GET/.well-known/jwks.jsonJWKS エンドポイント。JWT 署名検証用の公開鍵セットを返します。
ベース URL

すべてのエンドポイントは https://<your-domain> をベース URL として使用します。ドメインはマーケットプレイスの管理画面から確認できます。

サービスアカウントの作成

API を利用するには、管理画面でサービスアカウントを作成し、Client ID と Client Secret を取得してください。サービスアカウントの作成手順は管理画面のドキュメントを参照してください。

Token エンドポイント​

POST/api/v1/auth/external-service-token

Client Credentials フローでアクセストークンを発行します。サービスアカウントの認証情報（Client ID / Client Secret）を使用して認証します。

リクエストヘッダー​

ヘッダー必須説明
Content-TypeJSON ボディ使用時application/json（Basic 認証の場合は不要）

リクエストボディ​

パラメータ型必須説明
client_idstring必須サービスアカウントの Client ID（管理画面で発行）
client_secretstring必須サービスアカウントの Client Secret（管理画面で発行）

リクエスト例​

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"
  }'

レスポンスフィールド（200 OK）​

フィールド型説明
successbooleanリクエストの成否（成功時は true）
access_tokenstringJWT 形式のアクセストークン
token_typestringBearer
expires_innumberアクセストークンの有効期限（秒）
scopestring付与されたスコープ（スペース区切り）

レスポンス例​

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

マーケットプレイス版ではリフレッシュトークンは発行されません。トークンの有効期限が切れた場合は、同じ手順で新しいトークンを取得してください。

エラーレスポンス​

ステータスエラーコード説明
400missing_parametersclient_id または client_secret が不足
401auth_errorクライアント認証に失敗（Client ID / Secret が不正）
500server_errorサーバー内部エラー
503network_error認証基盤との通信に失敗
JSON
{
  "success": false,
  "error": "認証情報が正しくありません",
  "message": "認証情報が正しくありません",
  "code": "auth_error"
}

JWKS エンドポイント​

GET/.well-known/jwks.json

JWT 署名検証用の公開鍵セット（JSON Web Key Set）を返します。アクセストークンの署名を検証する場合に使用します。

リクエスト例​

curl
curl https://<your-domain>/.well-known/jwks.json

レスポンスフィールド（200 OK）​

フィールド型説明
keysarrayJWK（JSON Web Key）オブジェクトの配列
keys[].kidstring鍵 ID。JWT ヘッダーの kid と照合して検証に使用する鍵を特定
keys[].ktystring鍵タイプ（例: "RSA"）
keys[].algstringアルゴリズム（例: "RS256"）
keys[].usestring鍵の用途。"sig"（署名検証）
keys[].nstringRSA 公開鍵のモジュラス（Base64url エンコード）
keys[].estringRSA 公開鍵の指数（Base64url エンコード）

レスポンスヘッダー​

ヘッダー説明
Cache-Controlpublic, max-age=600

レスポンス例​

JSON
{
  "keys": [
    {
      "kid": "...",
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "n": "...",
      "e": "AQAB"
    }
  ]
}
注記

鍵のローテーションが行われた場合、kid（Key ID）が変更されます。署名検証時は JWT ヘッダーの kid と一致する鍵を使用してください。鍵はキャッシュ可能ですが、定期的な再取得を推奨します。

JWT クレーム構造​

アクセストークンに含まれる JWT クレーム（ペイロード）の構造です。署名アルゴリズムは RS256 です。

標準クレーム​

クレーム型説明
substringサービスアカウント ID（UUID）
issstring発行者 URL（例: https://<your-domain>/realms/<realm>）
audstring固定値 "account"
expnumber有効期限（Unix タイムスタンプ）
iatnumber発行日時（Unix タイムスタンプ）
jtistringJWT ID。トークンを一意に識別する ID
typstringトークン種別（"Bearer"）
azpstringAuthorized Party（トークンを要求したクライアント ID）
scopestring付与されたスコープ（スペース区切り）
acrstring認証コンテキストクラス

ユーザー情報​

サービスアカウント作成時に認証基盤が自動生成する内部識別子です。実在のユーザーを表すものではないため、アプリケーション側で表示・利用する必要はありません。

クレーム型説明
emailstring認証基盤が付与する内部用の識別子
email_verifiedboolean認証基盤が付与する内部用フラグ（常に true）
preferred_usernamestring認証基盤が付与する内部用の識別子

サービスアカウント情報​

クレーム型説明
client_idstringクライアント ID
clientHoststringリクエスト元ホスト
clientAddressstringリクエスト元 IP アドレス

ロール​

認証基盤の内部制御で使われるロール情報です。アプリケーション側で参照する必要はありません。

クレーム型説明
realm_access.rolesstring[]認証基盤が付与する Realm 配下のロール一覧
resource_access.account.rolesstring[]認証基盤が付与するクライアント配下のロール一覧

JWT Access Token Payload 例​

JSON
{
  "exp": 1776713919,
  "iat": 1776627519,
  "jti": "trrtcc:abc12345-6789-4def-8abc-0123456789ab",
  "iss": "https://<your-domain>/realms/<realm>",
  "aud": "account",
  "sub": "11111111-2222-3333-4444-555555555555",
  "typ": "Bearer",
  "azp": "my-service-account",
  "acr": "1",
  "realm_access": {
    "roles": ["..."]
  },
  "resource_access": {
    "account": {
      "roles": ["..."]
    }
  },
  "scope": "openid email profile",
  "email_verified": true,
  "clientHost": "192.168.1.100",
  "preferred_username": "service-account-my-service-account",
  "clientAddress": "192.168.1.100",
  "email": "my-service-account@serviceaccount.local",
  "client_id": "my-service-account"
}

クライアント認証​

トークンエンドポイントでは、以下のいずれかの方式でクライアント認証を行います。

JSON ボディ​

リクエストボディに client_id と client_secret を JSON で含めます。

JSON
{"client_id": "xxx", "client_secret": "yyy"}

Basic 認証（推奨）​

Authorization ヘッダーに Basic 認証で送信します。リクエストボディは不要です。

Authorization: Basic base64(client_id:client_secret)

Basic 認証でのリクエスト例​

curl
curl -X POST https://<your-domain>/api/v1/auth/external-service-token \
  -u "your_client_id:your_client_secret"

エラーコード​

認証エンドポイントは JSON 形式のエラーレスポンスを返します。すべてのエラーレスポンスには success: false が含まれます。

エラーレスポンス形式​

フィールド型説明
successboolean常に false
errorstringエラーメッセージ
messagestringエラーメッセージ（error と同値）
codestringエラーコード（機械処理用）
JSON
{
  "success": false,
  "error": "client_id, client_secret は必須です",
  "message": "client_id, client_secret は必須です",
  "code": "missing_parameters"
}

エラーコード一覧​

ステータスエラーコード説明
400missing_parameters必須パラメータ（client_id / client_secret）が不足
401auth_errorクライアント認証に失敗（Client ID / Secret が不正）
500server_errorサーバー内部エラー
503network_error認証基盤との通信に失敗