適したシナリオ:サードパーティアプリ / Agent / MCP クライアント / 自動化ワークフローを開発しており、ユーザーが Ace Data Cloud アカウントでワンクリックログインし、必要に応じてプラットフォーム上のリソースにアクセスできるようにしたい場合。ユーザーが手動で API Key をコピー&ペーストする必要はありません。
用語 & エンドポイント早見表
すべてのエンドポイントはhttps://auth.acedata.cloud にあり、Discovery エンドポイントを通じていつでも最新のアドレスを取得できます:
サポートされる機能:
response_type=code、grant_types=authorization_code, refresh_token、code_challenge_methods=S256, plain、クライアント認証方式 client_secret_post(機密クライアント)/ none(PKCE 公開クライアント)。
権限範囲(Scope)
「最小権限」に従って申請してください。ユーザーは認可ページで、あなたが申請した各権限を確認できます。 ID 系(OIDC 互換)
プラットフォームリソース系
集約系(自動展開)
特殊
典型的な組み合わせ:サードパーティの「ワンクリックログイン」=openid profile;MCP / IDE クライアントで Key の自動設定が必要 =openid profile credentials:read credentials:write;完全な管理コンソール =openid profile email platform offline_access。
ステップ 1:OAuth アプリを登録する
auth.acedata.cloud/user/oauth-apps を開く →「アプリを作成」を選択し、以下を入力します:- アプリ名 / 説明 / ロゴ:ユーザーの認可同意ページに表示されます。
- クライアントタイプ(Client Type):
- 機密(confidential)——バックエンドがあり、
client_secretを安全に保管できる場合(Web サービス、バックエンドサービス)。 - 公開(public)——純粋なフロントエンド / デスクトップ / CLI / モバイルで、秘密鍵を保管できない場合。PKCE を使用する必要があります。
- 機密(confidential)——バックエンドがあり、
- コールバック URL(Redirect URIs):認可完了後にユーザーがリダイレクトされるアドレスです。認可開始時に渡す
redirect_uriと完全に一致している必要があります。複数入力できます。 - 権限範囲(Scopes):前節で必要な scope を選択します。
client_id を取得できます。機密クライアントの場合はさらに client_secret が一度だけ表示されます——すぐに保存してください。閉じると再度確認できません(詳細ページの「シークレットをローテーション / Rotate Secret」で再生成でき、古いシークレットは直ちに無効になります)。
各アカウントで作成できる OAuth アプリは最大 20 個です。
ステップ 2:ユーザーを認可ページへリダイレクトする
アプリ内で、クエリパラメータを付けてユーザーのブラウザを認可ページへリダイレクトします:state:自分で生成するランダム文字列です。コールバック時にそのまま返され、CSRF 防止に使用されます。必ず検証してください。- PKCE(公開クライアントでは必須、機密クライアントでも推奨):まずランダムな
code_verifierを生成し、次にcode_challenge = BASE64URL( SHA256( code_verifier ) )を計算して、code_challengeを認可 URL に入れます。code_verifierはステップ 4 で使用するため、自分で保持しておいてください。
<redirect_uri>?error=access_denied&error_description=...&state=...。
認可コードの有効期限は 10 分で、一度しか使用できません。
ステップ 3:認可コードでトークンを取得する
バックエンド(機密クライアント)またはクライアント(PKCE 公開クライアント)で、code を使ってトークンエンドポイントを呼び出します。
機密クライアント(client_secret あり):
refresh_token は offline_access を申請した場合にのみ表示されます):
access_token は scope クレームを含む JWT です。有効期間は 15 日(expires_in の秒数)です。Refresh Token の有効期間は 30 日です。
ステップ 4:Access Token を使用して API を呼び出す
トークンをAuthorization: Bearer ヘッダーに入れるだけです。
ユーザー情報を取得する(UserInfo、フィールドは承認済み scope に応じてフィルタリングされます):
platform.acedata.cloud、scope に基づいて認可)。たとえば credentials:read を取得済みの場合:
scope クレームを検証します——トークンはユーザーが承認したリソースにのみアクセスできます。未承認のリソースにアクセスした場合は、403 が返されます。
トークンの更新
Access Token の有効期限が切れた後、Refresh Token を使用して新しいトークンペアに交換します(最初にoffline_access を申請している必要があります):
トークンの取り消し
実例:私たち自身の MCP サーバーもこのように接続しています
Ace Data Cloud の 15 以上の MCP サーバー(NanoBanana、Midjourney、Suno、Seedance、Kling…)で Claude Desktop / Cursor に表示される「Sign in with Ace Data Cloud」接続は、このフローを使用しています:これらはすべて 公開(PKCE) タイプの OAuth アプリケーションとして登録され、credentials 関連の scope を申請しています。ユーザーの承認後、MCP サーバーはユーザーに代わって api.acedata.cloud を呼び出せます——ユーザーが API Key を手動で貼り付ける必要はありません。あなたの接続方法もこれらと完全に同じです。
よくあるエラー
エラーレスポンスはすべて{ "error": "<code>", "error_description": "<人間が読める説明>" } です:
制限一覧
Studio ホームページへのサードパーティ OAuth アプリケーションの埋め込み
Studio の「設定 → ホームページ → ウェブサイトコンポーネント」で OAuth を有効化し、サードパーティアプリケーションのclient_id と登録済みのコールバックアドレスを設定できます。ウェブサイトとコールバックは HTTPS を使用し、同一のオリジン(プロトコル、ドメイン、ポート)である必要があり、Studio とは異なるオリジンでなければなりません。
設定内に
client_secret を記入してはなりません。アプリケーションキーはサードパーティのバックエンドにのみ保管できます。
コンポーネントが申請する権限は profile:read credentials:read です。訪問者ごとに個別の同意が必要です。サイト管理者がコンポーネントを設定しても、訪問者の承認を意味するものではありません。サードパーティページはランダムな
state と PKCE verifier を生成し、Studio に S256 challenge を送信します。Studio はコンポーネント領域で公式認可ページをホストし、ユーザーの同意後、サードパーティは使い捨ての認可コードを受け取り、token エンドポイントを呼び出して OAuth access token と交換し、その後
GET https://platform.acedata.cloud/api/v1/credentials/?user_id=<ユーザーID> にアクセスして既存の API Key を読み取ります。ユーザー ID は、前のステップの
GET https://auth.acedata.cloud/api/v1/users/me が返す id から取得します。認証情報一覧 API は user_id=me を受け付けません。Studio は自身のログイントークンをサードパーティへ送信せず、ユーザーの Key を直接読み取って注入することもありません。 公開クライアントは S256 PKCE を使用する必要があります。token を交換する際は、認可リクエスト時と完全に一致する
redirect_uri を渡す必要があります。認可コードは一度しか交換できません。認可前に、コールバックアドレスが登録済みかどうかが確認されます。 サードパーティページはメッセージプロトコルを実装する必要があります。既存の任意のウェブページを URL の入力だけで自動的に接続することはできません。
完全な例については、Studio OAuth コンポーネント統合ガイドを参照してください。 API Key の読み取りを承認することは、サードパーティにその Key の保存および使用を許可することを意味します。OAuth 承認を取り消しても、サードパーティがすでにコピーした Key は無効になりません。
ユーザーは別途 Key を取り消すかローテーションする必要があります。

