账号授权

获取认证状态

返回账号当前的认证流程状态，包括 code、QR、密码、Passkey、会话导入或认证终态。Passkey 状态包括 passkey_required、passkey_pending、passkey_confirmation 和 passkey_confirmation_sent；auth_payload 可能携带 WebAuthn public_key。

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/auth

调用前准备

在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。

参数从哪里取得

account_id: 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。获取账号

请求参数

请求头

X-Api-Key

string必填

工作区 API Key，工作区由该请求头解析得到。

路径参数

account_id

string必填

用于该 authentication 路由的标识符。

请求体

该接口无需 JSON 请求体。

如何理解结果

按文档解释响应字段和 HTTP 状态。204 成功响应没有响应体，排查时使用 X-Request-Id。下一步操作见相关链接。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "status": "awaiting_qr_scan",
    "auth_fields": [
      {
        "type": "qr_code",
        "required": true
      }
    ],
    "auth_payload": {
      "qr_code": "https://example.com/qr"
    },
    "expires_at": "2026-01-01T00:00:00Z",
    "last_error": ""
  }
}

响应体

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 失效。

format: date-time

last_error

string

最近一次认证错误，无错误时为空字符串。

响应

200

200 OK

请求成功，响应体示例如上。

401

未授权

X-Api-Key 请求头缺失或无效。

500

服务端错误

服务端遇到了未预期的错误。

失败后怎么处理

检查 HTTP 状态和 error.code/numeric_code，保存 request_id 用于排查。按原因修正参数、继续授权或检查运行态。重试发送及其他写操作前先确认上一次结果，避免重复操作。错误码参考

invalid_request · 10000 · 400: 检查必填字段、格式和渠道条件，修正请求后再调用。
invalid_api_key · 11001 · 401: 检查 X-Api-Key 是否正确、工作区是否有效。