認證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 路由嘅 ID。

請求內容

呢個介面唔需要 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"]
  }
}