認證POST

開始驗證碼認證

啟動驗證碼登入流程。呼叫後請以 /auth/code 提交渠道驗證碼；若需要兩步驗證，再呼叫 /auth/password。WhatsApp 也透過此端點進行手機號配對 — 電話號碼直接從帳號讀取（在建立帳號時透過 provider_data.phone 儲存），此處不必再傳。

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

請求標頭

X-Api-Key

string必填

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

Content-Type

string必填

傳送 JSON 請求內容時請使用 application/json。

路徑參數

account_id

string必填

用於該 authentication 路由的識別字。

請求內容

此介面無需 JSON 請求內容。

回應內容

account_id

string

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

status

string

當前認證流程狀態，例如 awaiting_code、awaiting_qr_scan、authorized 或 cancelled。

auth_fields

object[]

描述下一步驟所需的內容 — 每筆項目都帶有 type 以及是否為必填。

auth_payload

object

客戶端用以呈現下一步驟所需的素材，例如 qr_code 或 verify_code。

expires_at

string

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

回應

200

200 OK

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

400

請求錯誤

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

401

未授權

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

409

衝突

目前操作與既有的渠道帳號或資源衝突。

500

伺服器錯誤

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

請求

curl -X POST https://api.unifyport.ai/v1/accounts/{account_id}/auth/start \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

回應

{
  "data": {
    "account_id": "acc_example",
    "status": "awaiting_code",
    "auth_fields": [
      { "type": "code", "required": true }
    ],
    "auth_payload": {
      "verify_code": "ABCD-EFGH"
    },
    "expires_at": "2026-01-01T00:00:00Z"
  }
}