code を受け取り、さらに OAuth access token と交換します。
OAuth access token はアカウントリソースインターフェースへのアクセスに使用します;モデル API の呼び出しには対応する API Key を使用します。OAuth 認可によって API Key が自動作成されたり、サービスが有効化されたり、残高が増加したりすることはありません。
統合方式を選択する
標準リダイレクトでは
embed=studio、embed_origin または postMessage は不要です。Studio コンポーネントモードではホストが認可ページを作成し、メッセージブリッジを維持します;第三者は本文末尾のコンポーネントプロトコルに従って統合し、これら 2 つのパラメータを自ら組み立てないでください。
エンドポイントとディスカバリードキュメント
アプリケーション管理インターフェースにはアカウントログイン認証が必要であり、匿名動的登録(DCR)インターフェースではありません。MCP サービス独自のディスカバリー/登録アドレスは、本表のアカウント OAuth エンドポイントとは別の入口です;特定の MCP に接続する際は、そのサービスのドキュメントとディスカバリー結果に従って操作してください。
ディスカバリードキュメントは、エンドポイントとプロトコル機能を取得するために使用されます。現在のフローは OAuth token を返し、
id_token は返しません;openid scope が存在するという理由だけで、完全な OpenID Connect ログインフローとして処理しないでください。
権限範囲:現在の scope 名を使用する
scope はスペース区切りで、大文字と小文字を区別する権限名です。新しいアプリケーションでは、profile:read、email:read、phone:read などの具体的な権限を使用します。
申請可能な権限を取得する場所
ログイン後、OAuth アプリケーション一覧インターフェースGET /api/v1/oauth2/applications/ は available_scopes を返します;アプリケーション管理ページの権限セレクターは同じカタログを使用します。これは通常のセルフサービスアプリケーションが採用すべき選択可能な範囲です。
Discovery の scopes_supported にはプラットフォームが認識するすべての権限名が含まれますが、あなたのアプリケーションがそのすべてを申請できることを意味するものではありません。 実際の認可では同時に以下を確認します:
- 権限がこのアプリケーションタイプに委任することを許可されているか;
- 権限がこの OAuth アプリケーションの許可範囲に登録済みか;
- 現在のユーザーが要求された権限を保有しているか。
invalid_scope を返します。認可コードの交換時および更新時にも再確認され、権限が自動的に補完または昇格されることはありません。
通常のセルフサービスアプリケーションで選択可能な権限
以下は現在のカタログ(2026-10-09)です;統合時にはavailable_scopes を基準にしてください。
例えば、プロフィールのみを読み取るには
profile:read を使用します;メールアドレスも必要な場合は email:read を追加します;既存の API Key を読み取るには profile:read credentials:read を使用します。Key の作成または変更が実際に必要な場合にのみ credentials:write を申請し、更新が必要な場合は offline_access を追加してください。
一部の権限は、sites:read、sites:write、platform-tokens:read など、プラットフォームが承認した信頼済みアプリケーションのみで使用できます;その他の一部の権限は通常の第三者 OAuth アプリケーションには公開されていません。クライアントタイプ public/confidential は secret を保管できるかどうかを表すものであり、アプリケーションが信頼済みかどうかとは関係ありません。セルフサービスで作成したアプリケーションは、信頼済み権限を自ら有効にすることはできません。
account は指定された公式アカウント管理 MCP が使用するアカウント権限セレクターであり、第三者アプリケーション向けの「すべての権限」scope ではなく、他の scope と混用することはできません。第三者は必要な具体的権限を明示的に列挙する必要があります。
旧ドキュメントからの移行
旧名称は互換エイリアスとして受け付けられません。OAuth アプリケーションに登録した scopes、認可 URL、および自身の権限判定を同期して更新してください;アプリケーション設定を変更しても、すでに発行された token に権限が追加されることはなく、ユーザーによる再認可が必要です。
ステップ 1:OAuth アプリケーションを登録する
OAuth アプリケーション管理を開き、アプリケーションを作成して以下を入力します:- 名前、説明、アプリ Logo:認可ページのアプリ側に表示されます。
- クライアントタイプ:純粋なフロントエンド、モバイルまたはデスクトップクライアントは Public を選択します。バックエンドで secret を保管できるサービスは Confidential を選択します。
- コールバックアドレス:本番環境では HTTPS を使用し、アプリが実際にコールバックを処理する完全な URL を登録します。
- 権限:ページで提供されるディレクトリから、実際に必要な scopes を選択します。
client_id を保存します。Confidential クライアントは client_secret をサーバー側に保存し、HTML、フロントエンドのビルド変数、または URL に置くことはできません。Public クライアントは token の交換に secret を使用しません。登録レスポンスにこのフィールドが含まれていても、クライアントが秘匿できる認証情報として扱ってはなりません。
redirect_uri は、登録、認可、および token の交換時に、パス、末尾のスラッシュ、クエリパラメータを含めて完全に一致しなければなりません。各アカウントで作成できるアプリは最大 20 個です。Secret は作成/ローテーション時にのみ表示されます。ローテーション後、古い secret ではクライアント認証が必要な交換を続行できません。
ステップ 2:ボタンで認可を開始する
接続をクリックするたびに、新しいランダムなstate と code_verifier を生成し、以下を計算します。
state、verifier、およびコールバックアドレスをアプリ独自のセッションに保存してから、URL エンコードしたパラメータで認可ページを開きます。
plain も記載されていますが、Public クライアントは使用できません。Confidential クライアントにも S256 の使用を推奨します。認可開始時に PKCE を使用した場合、交換時には対応する verifier を必ず送信しなければなりません。
ユーザーが同意すると redirect_uri に戻り、クエリパラメータには code とそのまま返される state が含まれます。拒否された場合は、error=access_denied、エラー説明、および state が返されます。コールバックを処理する前に、state が今回のセッションと一致することを確認します。認可コードの有効期限は 10 分間で、交換は一度しかできません。失敗した場合は接続を再度開始し、古いコールバック URL を繰り返し更新しないでください。
ステップ 3:OAuth token を交換する
Public クライアントはブラウザまたはクライアントから直接交換します。Confidential クライアントは自らのバックエンドで交換します。リクエスト本文はフォームエンコードをサポートし、以下の変数はアプリが今回の認可で取得したデータを表します。client_secret フォームフィールドを追加する必要があります。現在は client_secret_post をサポートしています。HTTP Basic クライアント認証をサポート済みの方式と見なさないでください。
成功レスポンスから access_token、token_type、expires_in、および実際に付与された scope を読み取ります。offline_access がリクエストされ、かつ承認された場合にのみ refresh_token があります。OAuth access token をモデル API の API Key として扱わず、token、verifier、または認可コードをログ、分析イベント、共有リンクに書き込まないでください。
ステップ 4:ユーザー情報と API Key を読み取る
まず OAuth access token を使用して UserInfo をリクエストします。id はユーザー識別子です。profile:read または openid では基本プロフィール(例:username、nickname、avatar、is_verified、date_joined、registration_method)を読み取れます。メールアドレスには email:read、電話番号および地域には phone:read が必要です。未承認のフィールドが常に存在することに依存しないでください。
既存の API Key が必要で、かつ credentials:read が承認されている場合は、UserInfo の id をフィルタ条件として使用します。
count と items を使用し、Key フィールドは items[*].token であり、data[0].value ではありません。user_id=me はこのインターフェースで有効なユーザー ID ではありません。複数ページのデータは offset/limit に従って読み取りを続け、最初のページをすべての認証情報として扱わないでください。
アプリ、サービス、および有効状態に基づいて適用可能な認証情報を選択し、最初のものを盲目的に取得しないでください。リストが空であっても認可失敗を意味するわけではありません。ユーザーがまだ適用可能な Key を作成していない可能性があります。OAuth access token の権限制御と、API Key 自体のサービス範囲、クォータ、および有効期限の条件は異なる制約です。
API Key の読み取りを許可することは、第三者がそれを保存して使用できることを意味します。OAuth リクエストを取り消す、またはアプリのログイン状態をクリアしても、すでにコピーされた API Key は無効になりません。ユーザーは認証情報管理でその Key を個別に取り消すか、ローテーションする必要があります。
実行可能な Public / PKCE ブラウザ例
以下のページを登録したREDIRECT_URI にデプロイし、CLIENT_ID とコールバックアドレスを置き換えます。ボタンは標準認可を開始し、同じページに戻った後で個人プロフィールと既存 Key の数を読み取ります。この例では Key を表示も永続化もしません。実運用アプリでは実際の用途に応じて結果を利用します。まず独立したブラウザページで検証してから、後続の iframe 要件に従って受け入れ確認を行ってください。
sessionStorage を読み取るために、同一オリジンかつ同じブラウザタブ/iframe 内に存在する必要があります。本番アプリケーションでは、独自のセッション方式でトークンを管理し、有効期限を処理し、レスポンス受信後に認可 URL パラメータを削除する必要があります。ページのメイン画面は先にレンダリングし、ネットワーク障害は接続状態にのみ影響させる必要があります。
ホワイトラベルサイト内の iframe
顧客サイトが認可ページへ自ら遷移する場合
標準 OAuth パラメータと独自のコールバック処理を使用すればよいです。window.location.assign() は現在の iframe を遷移させ、親ページはホワイトラベルドメインに残ります。アイコンのために embed=studio を追加したり、Studio メッセージプロトコルを実装したりする必要はありません。
以下の条件を満たす必要があります。
- アプリページとコールバックページは HTTPS を使用し、実際にアクセス可能で、ホワイトラベル親ドメインによる iframe 埋め込みを許可すること。双方の
Content-Security-Policy: frame-ancestorsとX-Frame-Optionsを確認してください。 - sandbox はページに必要なスクリプト、フォーム、オリジン/ストレージ機能を許可すること。ポップアップログインをサポートする場合は、対応するポップアップ機能も必要です。Studio が提供する Website コンポーネント設定を優先して使用してください。
- ブラウザが現在の埋め込みシナリオで、認可状態に必要なストレージの使用を許可していること。ホワイトラベルサイトのログイン状態と AuthFrontend のログイン状態は異なる可能性があるため、ホワイトラベルサイトにログインしていれば認可ページにもログイン済みであるとは仮定しないでください。
- コールバック内の token 交換サービスが利用可能で、クロスオリジンリクエストがアプリオリジンに対して許可されていること。DNS、CORS、HTTP エラーはいずれも再試行可能な状態として表示し、ページ全体のレンダリングを停止させてはなりません。
Studio の現在のアカウントを使用して認可する場合
Studio の「設定 → ホーム → Website コンポーネント」で OAuth を有効にし、client_id と登録済みのコールバックアドレスを入力します。Website とコールバックは同じ HTTPS オリジンを使用し、Studio オリジンとは異なる必要があります。サードパーティページでは次のことが必要です。
- 正確な親サイト origin に
acedatacloud:oauth:readyを送信し、acedatacloud:oauth:initを受信して検証すること。 - ボタンで state と PKCE verifier を生成し、
acedatacloud:oauth:authorize(state、S256 challenge)を送信すること。verifier は自分のページ内に保持します。 - 親ウィンドウ、origin、state を検証し、
acedatacloud:oauth:result内の code または error を処理して、標準 token エンドポイントで交換すること。 Studio はコンポーネント領域に認可ページを表示し、ユーザーが同意した後にメッセージで認可コードを返します。アプリケーションはリダイレクトする必要がありません。ログインしていない場合はlogin_requiredを返し、拒否された場合はaccess_deniedを返し、待機がタイムアウトした場合はauthorization_timeoutを返します。アカウントの変更によりアプリケーション iframe が再構築され、未完了の認可がキャンセルされます。
profile:read credentials:read をリクエストしており、offline_access は含まれません。必ず refresh token を受け取れるとは想定しないでください。embed=studio、embed_origin は Studio ホストと認可ページによって維持され、クライアントページはメッセージプロトコルに従うだけで構いません。
完全なボタンの例については、Studio ウェブサイトコンポーネント OAuth 統合ガイド を参照してください。
ライフサイクル、更新、および取り消し
Access token のデフォルト有効期限は 15 日です。各レスポンスのexpires_in に基づいて更新または再認可を予定してください。refresh token のデフォルト有効期限は 30 日であり、期限はサービス設定の影響を受けます。これら 2 つの値を恒久的な保証としてハードコードしないでください。
offline_access が許可された後、次を呼び出せます。
よくあるエラーと受け入れ基準
納品前に少なくとも、正しいコールバック、拒否、誤った state、期限切れ/使用済み code、Key なし、ネットワーク障害、token の期限切れ、必要な scope の不足、および iframe シナリオでの初回ログインとアカウント切り替えを検証してください。テスト証拠には完全な code、token、または API Key を保存しないでください。
二段階認証と再認可
ユーザーが二段階認証を有効にした後、Ace Data Cloud は認可ページ内で認証アプリの確認コードまたはワンタイム復旧コードの検証を完了してから、認可コードを渡します。あなたのアプリケーションは標準 OAuth フローを継続して使用し、認証アプリの秘密鍵または復旧コードをユーザーに要求、保存、転送してはいけません。 ユーザーが二段階認証を有効化、変更、無効化した場合、またはアカウントを復旧した後は、以前のアカウントセッション、refresh token、および関連するプラットフォーム認可 token が無効になる可能性があります。無効なセッションまたはinvalid_grant を受け取った場合は、ユーザーに見える認可フローを再度開始してください。古い認可コードを繰り返し使用したり、検証を回避しようとしたりしないでください。通常のモデル API Key の認証方式は変更されません。アカウントの乗っ取りが疑われる場合は、影響を受ける API Key を別途確認して取り消してください。
