账号授权
开始扫码认证
为 auth_mode=qrcode 的渠道启动扫码登录。可轮询 /auth 或调用 /auth/qr/check 获取 QR 内容；部分 provider 通过 webhook 异步推送 QR，而不是在响应体里同步返回。
https://api.unifyport.ai/v1/accounts/{account_id}/auth/qr/start调用前准备
在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。
参数从哪里取得
- account_id
- 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。 获取账号
请求参数
请求头
X-Api-Key工作区 API Key，工作区由该请求头解析得到。
Content-Type发送 JSON 请求体时使用 application/json。
路径参数
account_id用于该 authentication 路由的标识符。
请求体
该接口接收空 JSON 对象；请按请求示例发送 {}。
如何理解结果
按文档解释响应字段和 HTTP 状态。204 成功响应没有响应体，排查时使用 X-Request-Id。下一步操作见相关链接。
响应 200 OK
{
"request_id": "<REQUEST_ID>",
"data": {
"account_id": "acc_example",
"status": "awaiting_qr_scan",
"auth_payload": {
"qr_code": "https://example.com/qr"
},
"expires_at": "2026-01-01T00:00:00Z"
}
}
响应体
account_id该响应所对应的渠道账号。
provider渠道标识。调用其他接口时原样使用 API 返回的值；此接口的返回范围见下方枚举。
action本次请求的运行时动作。
status当前授权流程状态，例如 pending_auth、awaiting_qr_scan、awaiting_code、pending、passkey_required、passkey_pending、passkey_confirmation、passkey_confirmation_sent、authorized 或 failed。
auth_statusPasskey 动作返回的标准认证状态。
auth_payload当前步骤所需的标准载荷。普通二维码使用 qr_code；验证码步骤使用 type=code；Passkey 使用 type=passkey 和 public_key。互斥步骤的载荷不会同时出现。
expires_atRFC3339 时间戳，超过该时刻后当前 auth_payload 失效。
响应
200200 OK
请求成功，响应体示例如上。
400请求错误
请求体、路径或参数不合法。
401未授权
X-Api-Key 请求头缺失或无效。
409冲突
当前操作与已有的渠道账号或资源冲突。
500服务端错误
服务端遇到了未预期的错误。
502上游网关错误
渠道适配器或上游渠道未能完成该操作。
失败后怎么处理
检查 HTTP 状态和 error.code/numeric_code，保存 request_id 用于排查。按原因修正参数、继续授权或检查运行态。重试发送及其他写操作前先确认上一次结果，避免重复操作。 错误码参考
- invalid_request · 10000 · 400
- 检查必填字段、格式和渠道条件，修正请求后再调用。
- invalid_api_key · 11001 · 401
- 检查 X-Api-Key 是否正确、工作区是否有效。