アカウント認可
QR 認証を開始
auth_mode=qrcode のプロバイダ向けに QR ログインフローを開始します。/auth をポーリングするか /auth/qr/check を呼んで QR の内容を取得します。一部のプロバイダでは、QR は同期レスポンスではなく webhook 経由で非同期に届きます。
https://api.unifyport.ai/v1/accounts/{account_id}/auth/qr/start呼び出す前に
対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。
パラメーターの取得元
- account_id
- アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。 アカウント取得
リクエストパラメータ
ヘッダー
X-Api-Keyワークスペース API キー。このヘッダーからワークスペースを特定します。
Content-TypeJSON のリクエストボディを送る場合は application/json を使用します。
パスパラメータ
account_idauthentication ルートで使用される識別子。
リクエストボディ
このエンドポイントは空の JSON オブジェクトを受け取ります。リクエスト例どおり {} を送信してください。
結果の確認
記載された応答項目と HTTP 状態を確認します。204 成功には本文がありません。診断には X-Request-Id を使い、次は関連操作を参照します。
レスポンス 200 OK
{
"request_id": "<REQUEST_ID>",
"data": {
"account_id": "acc_example",
"status": "awaiting_qr_scan",
"auth_payload": {
"qr_code": "https://example.com/qr"
},
"expires_at": "2026-01-01T00:00:00Z"
}
}
レスポンスボディ
account_idこのレスポンスが対象とするプロバイダアカウント。
providerチャネルの識別子です。後続の呼び出しでは返された値をそのまま使ってください。この API の値は以下の enum を参照してください。
action要求されたランタイム操作。
status現在の認可フロー状態。pending_auth、awaiting_qr_scan、awaiting_code、pending、passkey_required、passkey_pending、passkey_confirmation、passkey_confirmation_sent、authorized、failed など。
auth_statusPasskey アクションが返す標準化済み認証状態。
auth_payload現在のステップに必要な標準ペイロード。QR は qr_code、認証コードステップは type=code、Passkey は type=passkey と public_key を使用します。相互排他的なステップのペイロードは同時には現れません。
expires_at現在の auth_payload が無効になる時刻の RFC3339 タイムスタンプ。
レスポンス
200200 OK
リクエスト成功。レスポンスボディの例を参照してください。
400Bad Request
リクエストボディ、パス、またはパラメータが不正です。
401Unauthorized
X-Api-Key ヘッダが欠落しているか無効です。
409Conflict
要求された操作が、既存のプロバイダアカウントまたはリソースと競合しています。
500Internal Server Error
サービスで予期しないエラーが発生しました。
502Bad Gateway
プロバイダアダプタまたは上流サービスが操作を完了できませんでした。
失敗時の対応
HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。 エラーリファレンス
- invalid_request · 10000 · 400
- 必須項目、形式、チャネルの条件を確認して修正します。
- invalid_api_key · 11001 · 401
- X-Api-Key とワークスペースの有効性を確認します。