認證POST

建立渠道授權會話

為 auth_mode=qrcode 的 WhatsApp 帳號建立短期託管授權會話。請在使用者瀏覽器開啟 authorize_url，並將完整 URL 視為敏感憑證，切勿記錄或分享。

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

請求標頭

X-Api-Key

string必填

工作區 API Key，工作區會由此標頭解析得到。

路徑參數

account_id

string必填

用於該 authentication 路由的識別字。

請求內容

此介面無需 JSON 請求內容。

回應內容

account_id

string

本回應所對應的渠道帳號。

provider

string

回應輸出的 canonical provider 名稱。whatsapp-protocol 僅支援 session 認證，目前支援 text、image 和聯絡人詳情；不支援 reply、mentions、聯絡人清單及寫入操作、會話或群組功能。可用性以部署註冊的 adapter 為準。

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，切勿記錄或分享完整值。

format: uri

expires_at

string

RFC3339 時間戳記，超過後當前的 auth_payload 即失效。

format: date-time

switchable

boolean

託管授權會話是否允許使用者切換認證模式。

available_auth_modes[]

string[]

託管授權會話中可用的認證模式。

回應

201

201 Created

請求成功，回應內容範例如上。

400

請求錯誤

請求內容、路徑或參數無效。

401

未授權

X-Api-Key 請求標頭缺少或無效。

500

伺服器錯誤

服務遇到了未預期的錯誤。

503

服務無法使用

所需的後端服務暫時無法使用。

請求

curl -X POST https://api.unifyport.ai/v1/accounts/{account_id}/auth-sessions \
  -H "X-Api-Key: <YOUR_API_KEY>"

回應

{
  "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"]
  }
}