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

認証ガイド

マーケットプレイス版のアクセストークン取得手順を解説します。

概要​

用途に応じて、2 つの認証フローを使い分けます。

アプリケーションシステム連携
認証フローAuthorization Code(PKCE)Client Credentials
用途社員が外部ツールから、自分のアカウントでログインして使う会社のシステムがサーバー間で使う
トークン取得ブラウザでログインし、認可コードを経由して取得サービスアカウントの認証情報で直接取得
リフレッシュトークンありなし(期限切れ後に再取得)
準備する所認証サーバーのコンソール管理コンソール

準備の手順は API 利用準備ガイド を、詳細仕様は 認証 API リファレンス を参照してください。

前提条件​

トークンを取る所と API は、ドメインが違います。トークンは認証サービス(または認証サーバーの外の入口)のドメイン、API は外部 API のドメインです。どちらも構築の時に管理者が決めたものです。

Authorization Code フロー​

社員が外部ツールでログインし、認可コードを経由してアクセストークンとリフレッシュトークンを取得する認証フローです。MCP 対応の AI クライアント(Claude Code・Codex など)は、この手順を自分で行います(AI クライアント接続ガイド(MCP))。自社のアプリでログインするときは、次の手順で行います。

1. 認可リクエスト​

ユーザーをブラウザで、認証サーバーの外の入口の認可エンドポイントにリダイレクトします。PKCE(S256)が必須です。

GET https://<認証サーバーの外の入口のドメイン>/realms/<realm>/protocol/openid-connect/auth?
response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=http://localhost:8765/callback
&scope=openid
&state=STATE_VALUE
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256
パラメータ必須説明
response_type必須code 固定
client_id必須認証サーバーのコンソールで作ったクライアントの ID
redirect_uri必須クライアントに登録した戻り先
scope必須openid を含めます
state推奨CSRF 対策のランダム値。戻ってきた値がリクエストの値と同じかを必ず確かめてください
code_challenge必須code_verifier の SHA-256 を base64url にした値
code_challenge_method必須S256 固定

2. ユーザー認証​

認証サーバーのログインの画面で、メイン画面と同じメールアドレスとパスワードでログインします。承認済みで、メールアドレスを確かめた利用者だけがログインできます(API 利用準備ガイドの手順どおりに作ったクライアントのとき)。

3. 認可コード受け取り​

ログインが済むと、ブラウザは redirect_uri にリダイレクトされます。URL に一時的な認可コード(code)が含まれます。

4. トークンの交換​

認可コードを、トークンエンドポイントでアクセストークンに換えます。公開のクライアントなので、client_secret は送りません。

curl
curl -X POST https://<認証サーバーの外の入口のドメイン>/realms/<realm>/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "client_id=YOUR_CLIENT_ID" \
-d "code=AUTHORIZATION_CODE" \
-d "redirect_uri=http://localhost:8765/callback" \
-d "code_verifier=CODE_VERIFIER"

応答の access_token を API の呼び出しに、refresh_token を次の取り直しに使います。

5. トークンの更新​

アクセストークンの期限が切れたら、リフレッシュトークンで取り直します。

curl
curl -X POST https://<認証サーバーの外の入口のドメイン>/realms/<realm>/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "client_id=YOUR_CLIENT_ID" \
-d "refresh_token=REFRESH_TOKEN"

Client Credentials フロー​

管理コンソールで作成したサービスアカウントの認証情報で、アクセストークンを取得します。ユーザーの介在はありません。サーバー側で次のリクエストを実行してください。

curl
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"
  • クライアントの認証は、Authorization ヘッダーの Basic 認証か、本文の client_id・client_secret のどちらか一方で送ります
  • <auth-domain> は、ご利用環境の認証サービスのドメインです(例: auth.example.com)

レスポンス例

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

認証情報が誤っているときは 401 Unauthorized({"error": "invalid_client", ...})が返ります。

これまでのトークンの口

これまでの POST https://<auth-domain>/api/v1/auth/external-service-token(本文は JSON の client_id・client_secret)も、引き続き使えます。応答は success・access_token・token_type・expires_in・scope です。

トークンの再取得​

Client Credentials フローではリフレッシュトークンは発行されません。アクセストークンの有効期限(expires_in に指定された秒数)が切れた場合は、同じリクエストを再度実行して新しいトークンを取得してください。

ベストプラクティス

有効期限を管理し、期限切れ前に新しいトークンを取得することで、API 呼び出しの中断を防げます。

スコープ​

マーケットプレイス版ではスコープによる制限はありません。どちらのフローのトークンでも、スコープで API を絞りません。

アクセストークンの利用​

取得したアクセストークンは、API リクエストの Authorization ヘッダーに Bearer トークンとして設定してください。

Authorization: Bearer <access_token>

すべての API エンドポイントで同じ形式を使用します。API の住所は https://<your-domain>/api(<your-domain> は外部 API のドメイン)です。