账号授权
创建渠道授权会话
为 auth_mode=qrcode 的 WhatsApp 账号创建短期托管授权会话。请在用户浏览器中打开 authorize_url，并将完整 URL 视为敏感凭证，切勿记录日志或分享。
https://api.unifyport.ai/v1/accounts/{account_id}/auth-sessions支持的渠道
调用前准备
在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。
参数从哪里取得
- account_id
- 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。 获取账号
请求参数
请求头
X-Api-Key工作区 API Key，工作区由该请求头解析得到。
路径参数
account_id用于该 authentication 路由的标识符。
请求体
该接口无需 JSON 请求体。
如何理解结果
按本次授权动作读取 status/auth_status 和实际返回的 auth_payload。需要用户操作时按渠道指南继续；authorized 表示授权完成，发送前仍需检查 runtime_status。
响应 201 Created
{
"request_id": "<REQUEST_ID>",
"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"
]
}
}
响应体
account_id该响应所对应的渠道账号。
provider渠道标识。调用其他接口时原样使用 API 返回的值；此接口的返回范围见下方枚举。
enum: whatsapp
auth_mode该授权会话的认证模式；当前为 qrcode。
status当前授权流程状态，例如 pending_auth、awaiting_qr_scan、awaiting_code、pending、passkey_required、passkey_pending、passkey_confirmation、passkey_confirmation_sent、authorized 或 failed。
auth_payload当前步骤所需的标准载荷。普通二维码使用 qr_code；验证码步骤使用 type=code；Passkey 使用 type=passkey 和 public_key。互斥步骤的载荷不会同时出现。
authorize_url包含不透明凭证的短期托管授权 URL，切勿记录或分享完整值。
format: uri
expires_atRFC3339 时间戳，超过该时刻后当前 auth_payload 失效。
format: date-time
switchable托管授权会话是否允许用户切换认证模式。
available_auth_modes[]托管授权会话中可用的认证模式。
响应
201201 Created
请求成功，响应体示例如上。
400请求错误
请求体、路径或参数不合法。
401未授权
X-Api-Key 请求头缺失或无效。
409冲突
当前操作与已有的渠道账号或资源冲突。
500服务端错误
服务端遇到了未预期的错误。
503服务不可用
所需的后端服务暂时不可用。
失败后怎么处理
检查 HTTP 状态和 error.code/numeric_code，保存 request_id 用于排查。按原因修正参数、继续授权或检查运行态。重试发送及其他写操作前先确认上一次结果，避免重复操作。 错误码参考
- invalid_request · 10000 · 400
- 检查必填字段、格式和渠道条件，修正请求后再调用。
- missing_api_key · 11000 · 401
- 检查 X-Api-Key 是否正确、工作区是否有效。
- invalid_api_key · 11001 · 401
- 检查 X-Api-Key 是否正确、工作区是否有效。