認証 API リファレンス
マーケットプレイス版の認証エンドポイント仕様、JWT クレーム構造、エラーコードのリファレンスです。サービスアカウント(システム連携)のトークンの口と、外部ツールでのログイン(アプリケーション)の口があります。
ベース URL
サービスアカウントのトークンの口は、以下の認証サービスのベース URL を使用します。<auth-domain> は、構築の時に管理者が決めた認証サービスのドメインに読み替えてください(例: auth.example.com)。外部ツールでのログインの口は、認証サーバーの外の入口のドメインです(外部ツールでのログイン)。
https://<auth-domain>認証エンドポイント一覧
サービスアカウントの認証情報で、Client Credentials フローでアクセストークンを取得します。
| メソッド | エンドポイント | 説明 |
|---|---|---|
| POST | /api/v1/oauth/token | 標準の形のトークンエンドポイント(RFC 6749)。Client Credentials フローでアクセストークンを発行します。 |
| POST | /api/v1/auth/external-service-token | これまでのトークンエンドポイント。Client Credentials フローでアクセストークンを発行します。 |
| GET | /.well-known/jwks.json | JWKS エンドポイント。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_type | string | 必須 | client_credentials を指定 |
client_id | string | — | 本文でクライアントを認証するとき(`client_secret_post`)に指定 |
client_secret | string | — | 本文でクライアントを認証するとき(`client_secret_post`)に指定 |
クライアントの認証は、Authorization ヘッダーの Basic 認証か、本文の client_id・client_secret のどちらか一方です。両方を送ると 400(invalid_request)です。
リクエスト例
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"curl -X POST https://<auth-domain>/api/v1/oauth/token \ -u "your_client_id:your_client_secret" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials"
import requests
response = requests.post(
"https://<auth-domain>/api/v1/oauth/token",
auth=("your_client_id", "your_client_secret"),
data={"grant_type": "client_credentials"},
)
print(response.json())const credentials = btoa("your_client_id:your_client_secret");
const response = await fetch("https://<auth-domain>/api/v1/oauth/token", {
method: "POST",
headers: {
"Authorization": "Basic " + credentials,
"Content-Type": "application/x-www-form-urlencoded",
},
body: new URLSearchParams({ grant_type: "client_credentials" }),
});
const data = await response.json();
console.log(data);form := url.Values{}
form.Set("grant_type", "client_credentials")
req, _ := http.NewRequest("POST", "https://<auth-domain>/api/v1/oauth/token", strings.NewReader(form.Encode()))
req.SetBasicAuth("your_client_id", "your_client_secret")
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|---|---|
access_token | string | JWT 形式のアクセストークン |
token_type | string | Bearer |
expires_in | number | アクセストークンの有効期限(秒) |
scope | string | 付与されたスコープ(スペース区切り。無いときは含まれません) |
応答には Cache-Control: no-store が付きます。リフレッシュトークンは発行されません。
エラーレスポンス
| ステータス | code | 説明 |
|---|---|---|
400 | invalid_request | クライアントの認証を 2 つの方式で送った、または Basic 認証の client_id と本文の client_id が違う |
401 | invalid_client | クライアントの認証が無い、または Client ID / Secret が正しくない(WWW-Authenticate ヘッダーが付きます) |
429 | rate_limit_exceeded | 同じ送り元と Client ID からの要求が多すぎる。時間をおいて再試行する(Retry-After ヘッダーがあれば、その秒数だけ待つ)。この応答の本文は、上の 400・401・500 の形(error が code)ではなく、success・error(説明の文)・message・code を持つ形です |
500 | server_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_id | string | 必須 | サービスアカウントの Client ID(管理コンソールで発行) |
client_secret | string | 必須 | サービスアカウントの Client Secret(管理コンソールで発行) |
リクエスト例
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}'curl -X POST https://<auth-domain>/api/v1/auth/external-service-token \
-H "Content-Type: application/json" \
-d '{
"client_id": "your_client_id",
"client_secret": "your_client_secret"
}'import requests
response = requests.post(
"https://<auth-domain>/api/v1/auth/external-service-token",
json={"client_id": "your_client_id", "client_secret": "your_client_secret"},
)
print(response.json())const response = await fetch("https://<auth-domain>/api/v1/auth/external-service-token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: "your_client_id",
client_secret: "your_client_secret",
}),
});
const data = await response.json();
console.log(data);payload, _ := json.Marshal(map[string]string{
"client_id": "your_client_id",
"client_secret": "your_client_secret",
})
resp, _ := http.Post("https://<auth-domain>/api/v1/auth/external-service-token", "application/json", bytes.NewBuffer(payload))
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|---|---|
success | boolean | リクエストの成否(成功時は true) |
access_token | string | JWT 形式のアクセストークン |
token_type | string | Bearer |
expires_in | number | アクセストークンの有効期限(秒) |
scope | string | 付与されたスコープ(スペース区切り) |
レスポンス例
{
"success": true,
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"scope": "openid profile email"
}
Client Credentials フローではリフレッシュトークンは発行されません。トークンの有効期限が切れた場合は、同じ手順で新しいトークンを取得してください。
エラーレスポンス
| ステータス | code | 説明 |
|---|---|---|
400 | missing_parameters | client_id または client_secret が不足 |
401 | auth_error | クライアント認証に失敗(Client ID / Secret が不正) |
429 | rate_limit_exceeded | 同じ送り元からの要求が多すぎる。時間をおいて再試行する(Retry-After ヘッダーがあれば、その秒数だけ待つ) |
500 | server_error | サーバー内部エラー(認証基盤と通信できないときを含む) |
{
"success": false,
"error": "認証情報が正しくありません",
"message": "認証情報が正しくありません",
"code": "auth_error"
}
JWKS エンドポイント
GET/.well-known/jwks.json
JWT 署名検証用の公開鍵セット(JSON Web Key Set)を返します。アクセストークンの署名を検証する場合に使用します。
リクエスト例
1curl https://<auth-domain>/.well-known/jwks.jsoncurl https://<auth-domain>/.well-known/jwks.json
import requests response = requests.get( "https://<auth-domain>/.well-known/jwks.json", ) print(response.json())
const response = await fetch("https://<auth-domain>/.well-known/jwks.json");
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://<auth-domain>/.well-known/jwks.json", nil)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)レスポンスフィールド(200 OK)
| フィールド | 型 | 説明 |
|---|---|---|
keys | array | JWK(JSON Web Key)オブジェクトの配列 |
keys[].kid | string | 鍵 ID。JWT ヘッダーの kid と照合して検証に使用する鍵を特定 |
keys[].kty | string | 鍵タイプ(例: "RSA") |
keys[].alg | string | アルゴリズム(例: "RS256") |
keys[].use | string | 鍵の用途。"sig"(署名検証) |
keys[].n | string | RSA 公開鍵のモジュラス(Base64url エンコード) |
keys[].e | string | RSA 公開鍵の指数(Base64url エンコード) |
レスポンスヘッダー
| ヘッダー | 説明 |
|---|---|
Cache-Control | public, max-age=600 |
レスポンス例
{
"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 です。
標準クレーム
| クレーム | 型 | 説明 |
|---|---|---|
sub | string | サービスアカウント ID(UUID) |
iss | string | 発行者 URL。認証サーバーの中の住所です(http://<認証サーバーの中の住所>/realms/<realm>) |
aud | string | 固定値 "account" |
exp | number | 有効期限(Unix タイムスタンプ) |
iat | number | 発行日時(Unix タイムスタンプ) |
jti | string | JWT ID。トークンを一意に識別する ID |
typ | string | トークン種別("Bearer") |
azp | string | Authorized Party(トークンを要求したクライアント ID) |
scope | string | 付与されたスコープ(スペース区切り) |
acr | string | 認証コンテキストクラス |
ユーザー情報
サービスアカウント作成時に認証基盤が自動生成する内部識別子です。実在のユーザーを表すものではないため、アプリケーション側で表示・利用する必要はありません。
| クレーム | 型 | 説明 |
|---|---|---|
email | string | 認証基盤が付与する内部用の識別子 |
email_verified | boolean | 認証基盤が付与する内部用フラグ(常に true) |
preferred_username | string | 認証基盤が付与する内部用の識別子 |
サービスアカウント情報
| クレーム | 型 | 説明 |
|---|---|---|
client_id | string | クライアント ID |
clientHost | string | リクエスト元ホスト |
clientAddress | string | リクエスト元 IP アドレス |
ロール
認証基盤の内部制御で使われるロール情報です。アプリケーション側で参照する必要はありません。
| クレーム | 型 | 説明 |
|---|---|---|
realm_access.roles | string[] | 認証基盤が付与する Realm 配下のロール一覧 |
resource_access.account.roles | string[] | 認証基盤が付与するクライアント配下のロール一覧 |
JWT Access Token Payload 例
{
"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 で含めます。
{"client_id": "xxx", "client_secret": "yyy"}
Basic 認証(推奨)
Authorization ヘッダーに Basic 認証で送信します。リクエストボディは不要です。
Authorization: Basic base64(client_id:client_secret)
Basic 認証でのリクエスト例
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 が含まれます。標準のトークンエンドポイントのエラーは 標準のトークンエンドポイント を参照してください。
エラーレスポンス形式
| フィールド | 型 | 説明 |
|---|---|---|
success | boolean | 常に false |
error | string | エラーメッセージ |
message | string | エラーメッセージ(error と同値) |
code | string | エラーコード(機械処理用) |
{
"success": false,
"error": "client_id, client_secret は必須です",
"message": "client_id, client_secret は必須です",
"code": "missing_parameters"
}
エラーコード一覧
| ステータス | code | 説明 |
|---|---|---|
400 | missing_parameters | 必須パラメータ(client_id / client_secret)が不足 |
401 | auth_error | クライアント認証に失敗(Client ID / Secret が不正) |
429 | rate_limit_exceeded | 同じ送り元からの要求が多すぎる。時間をおいて再試行する(Retry-After ヘッダーがあれば、その秒数だけ待つ) |
500 | server_error | サーバー内部エラー(認証基盤と通信できないときを含む) |