アカウント認可

プロバイダ認可セッションを作成

auth_mode=qrcode の WhatsApp アカウント向けに短期のホスト型認可セッションを作成します。authorize_url はユーザーのブラウザで開き、完全な URL を機密資格情報として扱い、ログや共有を避けてください。

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/auth-sessions

呼び出す前に

対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。

パラメーターの取得元

account_id: アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。アカウント取得

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

ワークスペース API キー。このヘッダーからワークスペースを特定します。

パスパラメータ

account_id

string必須

authentication ルートで使用される識別子。

リクエストボディ

このエンドポイントは JSON ボディを必要としません。

結果の確認

記載された応答項目と HTTP 状態を確認します。204 成功には本文がありません。診断には X-Request-Id を使い、次は関連操作を参照します。

レスポンス 201 Created

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "provider": "whatsapp",
    "auth_mode": "qrcode",
    "status": "passkey_required",
    "auth_payload": {
      "type": "passkey",
      "public_key": {
        "challenge": "<BASE64URL_CHALLENGE>"
      }
    },
    "authorize_url": "https://auth.example.com/authorize/whatsapp/<SESSION_TOKEN>",
    "expires_at": "2026-08-12T08:10:00Z",
    "switchable": false,
    "available_auth_modes": [
      "qrcode"
    ]
  }
}

レスポンスボディ

account_id

string

このレスポンスが対象とするプロバイダアカウント。

provider

string

チャネルの識別子です。後続の呼び出しでは返された値をそのまま使ってください。この API の値は以下の enum を参照してください。

enum: whatsapp

auth_mode

string

この認可セッションの認証モード。現在は qrcode です。

status

string

現在の認可フロー状態。pending_auth、awaiting_qr_scan、awaiting_code、pending、passkey_required、passkey_pending、passkey_confirmation、passkey_confirmation_sent、authorized、failed など。

auth_payload

object

現在のステップに必要な標準ペイロード。QR は qr_code、認証コードステップは type=code、Passkey は type=passkey と public_key を使用します。相互排他的なステップのペイロードは同時には現れません。

authorize_url

string

不透明な資格情報を含む短期ホスト型認可 URL。完全な URL をログや共有に含めないでください。

format: uri

expires_at

string

現在の auth_payload が無効になる時刻の RFC3339 タイムスタンプ。

format: date-time

switchable

boolean

ホスト型認可セッションで認証モードを切り替えられるかどうか。

available_auth_modes[]

string[]

ホスト型認可セッション内で利用できる認証モード。

レスポンス

201

201 Created

リクエスト成功。レスポンスボディの例を参照してください。

400

Bad Request

リクエストボディ、パス、またはパラメータが不正です。

401

Unauthorized

X-Api-Key ヘッダが欠落しているか無効です。

500

Internal Server Error

サービスで予期しないエラーが発生しました。

503

Service Unavailable

必要なバックエンドサービスが一時的に利用できません。

失敗時の対応

HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。エラーリファレンス

invalid_request · 10000 · 400: 必須項目、形式、チャネルの条件を確認して修正します。
invalid_api_key · 11001 · 401: X-Api-Key とワークスペースの有効性を確認します。