← API 参考
认证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_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"]
  }
}