認証ガイド
マーケットプレイス版のアクセストークン取得手順を解説します。
概要
用途に応じて、2 つの認証フローを使い分けます。
| アプリケーション | システム連携 | |
|---|---|---|
| 認証フロー | Authorization Code(PKCE) | Client Credentials |
| 用途 | 社員が外部ツールから、自分のアカウントでログインして使う | 会社のシステムがサーバー間で使う |
| トークン取得 | ブラウザでログインし、認可コードを経由して取得 | サービスアカウントの認証情報で直接取得 |
| リフレッシュトークン | あり | なし(期限切れ後に再取得) |
| 準備する所 | 認証サーバーのコンソール | 管理コンソール |
準備の手順は API 利用準備ガイド を、詳細仕様は 認証 API リファレンス を参照してください。
前提条件
- マーケットプレイスで購入した AGENTIC STAR 環境のセットアップが完了していること
- アプリケーション: 管理者が外部ツールでのログインの入口を開け、認証サーバーのコンソールで外部ツールのクライアントを作成済みであること(API 利用準備ガイド — アプリケーションの作成手順)
- システム連携: 管理コンソールでサービスアカウントを作成済みで、
Client IDとClient Secretを取得済みであること(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 -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 -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 -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)
レスポンス例
{
"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 リファレンス(プロジェクト))
- システム連携のトークンで呼べる API は、システム連携 API リファレンス にあるものです
アクセストークンの利用
取得したアクセストークンは、API リクエストの Authorization ヘッダーに Bearer トークンとして設定してください。
Authorization: Bearer <access_token>
すべての API エンドポイントで同じ形式を使用します。API の住所は https://<your-domain>/api(<your-domain> は外部 API のドメイン)です。