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

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

マーケットプレイス版の認証エンドポイント仕様、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-Type必須application/json

リクエストボディ​

パラメータ型必須説明
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"
}
注記

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

エラーレスポンス​

ステータスcode説明
400missing_parametersclient_id または client_secret が不足
401invalid_credentialsクライアント認証に失敗（Client ID / Secret が不正）
500server_errorサーバー内部エラー

エラーレスポンス例​

JSON
{
  "success": false,
  "error": "認証情報が正しくありません",
  "message": "認証情報が正しくありません",
  "code": "invalid_credentials"
}

JWKS エンドポイント​

GET /.well-known/jwks.json​

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

リクエスト例​

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

レスポンスヘッダー​

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

レスポンス例​

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
audstring対象者（Client ID）
expnumber有効期限（Unix タイムスタンプ）
iatnumber発行日時（Unix タイムスタンプ）
azpstringAuthorized Party（トークンを要求したクライアント ID）
scopestring付与されたスコープ（スペース区切り）
acrstring認証コンテキストクラス

ユーザー情報​

クレーム型説明
emailstringサービスアカウントのメールアドレス
email_verifiedbooleanメールアドレスが検証されているか
preferred_usernamestringユーザー名

プロフィール（オプション）​

管理画面でサービスアカウントにユーザー属性を設定した場合のみ出力されます。

クレーム型説明
organizationstring所属組織
jobstring役職
biostring自己紹介

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

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

ロール​

クレーム型説明
realm_access.rolesstring[]付与されたロール（例: user）

JWT Access Token Payload 例​

JSON
{
  "sub": "7c6f8a3c-2e1b-4d9f-a5e2-1b4c8d3f2e1a",
  "iss": "https://your-domain/auth",
  "aud": "account",
  "exp": 1678886400,
  "iat": 1678884600,
  "azp": "my-service-account",
  "acr": "1",
  "scope": "openid email profile",
  "email": "service@example.com",
  "email_verified": true,
  "preferred_username": "service-account-my-service",
  "client_id": "my-service-account",
  "clientHost": "192.168.1.100",
  "clientAddress": "192.168.1.100",
  "realm_access": {
    "roles": ["user"]
  }
}

クライアント認証​

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

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

エラーコード一覧​

codeステータス説明
missing_parameters400必須パラメータ（client_id / client_secret）が不足
invalid_credentials401クライアント認証に失敗（Client ID / Secret が不正）
rate_limit_exceeded429リクエスト回数の上限を超過
server_error500サーバー内部エラー