認證POST

開始驗證碼認證

啟動驗證碼登入流程。Call 完之後請用 /auth/code 提交渠道驗證碼；如果需要兩步驗證，再 call /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 路由嘅 ID。

請求內容

呢個介面接收空 JSON 物件；請跟請求例子傳送 {}。

回應內容

account_id

string

呢個回應所指嘅渠道帳號。

status

string

目前授權流程狀態，例如 pending_auth、awaiting_qr_scan、awaiting_code、pending、passkey_required、passkey_pending、passkey_confirmation、passkey_confirmation_sent、authorized 或 failed。

auth_fields[]

object[]

講明下一步要乜嘢 — 每一項都帶住一個 type，仲有係咪必填。

type

string

下一步認證要求嘅輸入類型，例如 code 或 password。

required

boolean

呢個認證輸入係咪一定要提供。

label

string

渠道方提供嘅輸入顯示標籤（如有）。

placeholder

string

渠道方提供嘅輸入提示文字（如有）。

auth_payload

object

目前步驟所需嘅標準載荷。普通 QR 用 qr_code；驗證碼步驟用 type=code；Passkey 用 type=passkey 同 public_key。互斥步驟嘅載荷唔會同時出現。

expires_at

string

RFC3339 時間戳，過咗呢個時間之後而家個 auth_payload 就唔再有效。

回應

200

200 OK

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

400

請求錯誤

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

401

未授權

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

409

衝突

目前操作同現有嘅渠道帳號或者資源衝突。

500

伺服器錯誤

服務遇到咗未預期嘅錯誤。

502

上游閘道錯誤

渠道轉接器或者上游渠道未能完成呢個操作。

請求

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