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

認証 API リファレンス

マーケットプレイス版の認証エンドポイント仕様、JWT クレーム構造、エラーコードのリファレンスです。サービスアカウント(システム連携)のトークンの口と、外部ツールでのログイン(アプリケーション)の口があります。

ベース URL​

サービスアカウントのトークンの口は、以下の認証サービスのベース URL を使用します。<auth-domain> は、構築の時に管理者が決めた認証サービスのドメインに読み替えてください(例: auth.example.com)。外部ツールでのログインの口は、認証サーバーの外の入口のドメインです(外部ツールでのログイン)。

Marketplace
https://<auth-domain>

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

Marketplace

サービスアカウントの認証情報で、Client Credentials フローでアクセストークンを取得します。

メソッドエンドポイント説明
POST/api/v1/oauth/token標準の形のトークンエンドポイント(RFC 6749)。Client Credentials フローでアクセストークンを発行します。
POST/api/v1/auth/external-service-tokenこれまでのトークンエンドポイント。Client Credentials フローでアクセストークンを発行します。
GET/.well-known/jwks.jsonJWKS エンドポイント。JWT 署名検証用の公開鍵セットを返します。
サービスアカウントの作成

API を利用するには、管理コンソールでサービスアカウントを作成し、Client ID と Client Secret を取得してください(API 利用準備ガイド — システム連携の作成手順)。

標準のトークンエンドポイント​

POST/api/v1/oauth/token

Client Credentials フローでアクセストークンを発行します。本文・応答・エラーは RFC 6749 の形です(RFC 6749 4.4)。

リクエストヘッダー​

ヘッダー必須説明
Content-Type必須application/x-www-form-urlencoded
Authorization—Basic 認証(`client_secret_basic`)でクライアントを認証するときに付けます

リクエストボディ​

パラメータ型必須説明
grant_typestring必須client_credentials を指定
client_idstring—本文でクライアントを認証するとき(`client_secret_post`)に指定
client_secretstring—本文でクライアントを認証するとき(`client_secret_post`)に指定

クライアントの認証は、Authorization ヘッダーの Basic 認証か、本文の client_id・client_secret のどちらか一方です。両方を送ると 400(invalid_request)です。

リクエスト例​

Get token (Client Credentials)
1curl -X POST https://<auth-domain>/api/v1/oauth/token \
2-u "your_client_id:your_client_secret" \
3-H "Content-Type: application/x-www-form-urlencoded" \
4-d "grant_type=client_credentials"

レスポンスフィールド(200 OK)​

フィールド型説明
access_tokenstringJWT 形式のアクセストークン
token_typestringBearer
expires_innumberアクセストークンの有効期限(秒)
scopestring付与されたスコープ(スペース区切り。無いときは含まれません)

応答には Cache-Control: no-store が付きます。リフレッシュトークンは発行されません。

エラーレスポンス​

ステータスcode説明
400invalid_requestクライアントの認証を 2 つの方式で送った、または Basic 認証の client_id と本文の client_id が違う
401invalid_clientクライアントの認証が無い、または Client ID / Secret が正しくない(WWW-Authenticate ヘッダーが付きます)
429rate_limit_exceeded同じ送り元と Client ID からの要求が多すぎる。時間をおいて再試行する(Retry-After ヘッダーがあれば、その秒数だけ待つ)。この応答の本文は、上の 400・401・500 の形(error が code)ではなく、success・error(説明の文)・message・code を持つ形です
500server_errorトークンを発行できない(時間をおいて再試行してください)

400・401・500 の本文は {"error": "...", "error_description": "..."} で、上の表の「code」は error の値です。429 だけは、code の項目に表の値が入ります。

Token エンドポイント​

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

これまでのトークンエンドポイントです。Client Credentials フローでアクセストークンを発行します。サービスアカウントの認証情報(Client ID / Client Secret)を使用して認証します。新しく作るシステムには、標準のトークンエンドポイント を勧めます。

リクエストヘッダー​

ヘッダー必須説明
Content-Type—application/json。client_id・client_secret を JSON ボディで送るときは必要です(Basic 認証だけで送るときは不要)

リクエストボディ​

パラメータ型必須説明
client_idstring必須サービスアカウントの Client ID(管理コンソールで発行)
client_secretstring必須サービスアカウントの Client Secret(管理コンソールで発行)

リクエスト例​

Get token (service account)
1curl -X POST https://<auth-domain>/api/v1/auth/external-service-token \
2-H "Content-Type: application/json" \
3-d '{
4 "client_id": "your_client_id",
5 "client_secret": "your_client_secret"
6}'

レスポンスフィールド(200 OK)​

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

レスポンス例​

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

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

エラーレスポンス​

ステータスcode説明
400missing_parametersclient_id または client_secret が不足
401auth_errorクライアント認証に失敗(Client ID / Secret が不正)
429rate_limit_exceeded同じ送り元からの要求が多すぎる。時間をおいて再試行する(Retry-After ヘッダーがあれば、その秒数だけ待つ)
500server_errorサーバー内部エラー(認証基盤と通信できないときを含む)
JSON
{
"success": false,
"error": "認証情報が正しくありません",
"message": "認証情報が正しくありません",
"code": "auth_error"
}

JWKS エンドポイント​

GET/.well-known/jwks.json

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

リクエスト例​

Get JWKS
1curl https://<auth-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 と一致する鍵を使用してください。鍵はキャッシュ可能ですが、定期的な再取得を推奨します。

外部ツールでのログイン​

外部ツールでのログイン(Authorization Code フロー+PKCE)の口です。管理者が認証サーバーの外の入口を開けた環境でだけ使えます(API 利用準備ガイド)。どれも OpenID Connect の標準の口です。

発行元(iss)は https://<認証サーバーの外の入口のドメイン>/realms/<realm> です。MCP 対応の AI クライアントが見つける認証サーバーも、この値です(MCP API リファレンス — 認証)。

メソッドエンドポイント説明
GET/realms/<realm>/.well-known/openid-configuration案内の文書(OpenID Connect Discovery)。下の口の住所が入っています
GET/.well-known/oauth-authorization-server/realms/<realm>案内の文書(RFC 8414)
GET/realms/<realm>/protocol/openid-connect/auth認可エンドポイント
POST/realms/<realm>/protocol/openid-connect/tokenトークンエンドポイント(認可コードの交換・リフレッシュトークンでの更新)
GET/realms/<realm>/protocol/openid-connect/certs署名の検証用の公開鍵(JWKS)
GET/realms/<realm>/protocol/openid-connect/userinfo利用者の情報
GET/realms/<realm>/protocol/openid-connect/logoutログアウト
POST/realms/<realm>/protocol/openid-connect/revokeトークンの取り消し
  • 住所は、どれも https://<認証サーバーの外の入口のドメイン> からの相対パスです
  • 認可エンドポイントでは PKCE(code_challenge_method=S256)が必須です。クライアントは公開のクライアントなので、トークンエンドポイントに client_secret は送りません
  • クライアントを自動で登録する口(動的クライアント登録)はありません
  • 手順の例は 認証ガイド — Authorization Code フロー にあります

この口で出るアクセストークンは利用者のトークンです。sub は利用者の ID、azp はクライアントの ID で、email が入ります。client_id のクレームは入りません。

JWT クレーム構造​

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

標準クレーム​

クレーム型説明
substringサービスアカウント ID(UUID)
issstring発行者 URL。認証サーバーの中の住所です(http://<認証サーバーの中の住所>/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": "http://<認証サーバーの中の住所>/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"
}

クライアント認証​

これまでのトークンエンドポイント(/api/v1/auth/external-service-token)では、以下のいずれかの方式でクライアント認証を行います。

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://<auth-domain>/api/v1/auth/external-service-token \
-u "your_client_id:your_client_secret"

エラーコード​

これまでのトークンエンドポイント(/api/v1/auth/external-service-token)は 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説明
400missing_parameters必須パラメータ(client_id / client_secret)が不足
401auth_errorクライアント認証に失敗(Client ID / Secret が不正)
429rate_limit_exceeded同じ送り元からの要求が多すぎる。時間をおいて再試行する(Retry-After ヘッダーがあれば、その秒数だけ待つ)
500server_errorサーバー内部エラー(認証基盤と通信できないときを含む)