认证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

当前授权流程状态，例如 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_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"
  }
}