完成密码登录的 2FA 验证

两步验证登录

🔓 无需鉴权（登录流程）。签发新登录 Session 时可能返回 409 AUTH_SESSION_LIMIT 或 429 AUTH_SESSION_ISSUANCE_LIMIT。

本地契约说明

路由：POST /api/user/login/2fa

注册处理器：github.com/QuantumNous/new-api/controller.Verify2FALogin。

消费方：web_vue。

鉴权：匿名。路由未挂 UserAuth；仍受限流、Turnstile、一次性 flow token 或服务端业务校验约束。

字段状态：controller-confirmed-session。字段为动态上游数据或回调负载时，文档会明确标记，不能补造 Schema。

页面/功能：OTP 页使用密码登录返回的短期 flow_token 完成 2FA。

前端传参：必传 code（TOTP 或备用码）和 flow_token。code 与 flow_token 都只保存在当前页面内存，提交后立即清理。

前端展示：成功后更新内存 access token、会话和用户资料；服务端同时写入 HttpOnly refresh Cookie。

调试：使用本操作的 x-debug 里的占位符；示例不含真实密码、API Key、签名、Cookie 或 Provider 密钥。

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200

application/json

管理端业务响应。HTTP 200 不代表业务成功，必须检查 success。

Bodyapplication/json

示例

成功业务失败仍可能使用 HTTP 200

{
    "success": true,
    "message": "",
    "data": {
        "access_token": "<redacted-access-token>",
        "token_type": "Bearer",
        "access_expires_at": 1786650900,
        "session": {
            "sid": "00000000-0000-0000-0000-000000000001",
            "current": true,
            "login_method": "2fa",
            "ip": "127.0.0.1",
            "user_agent": "debug-browser",
            "created_at": 1786650000,
            "last_active_at": 1786650000,
            "expires_at": 1789242000
        },
        "user": {
            "id": 1,
            "username": "debug-user",
            "display_name": "Debug User",
            "role": 1,
            "status": 1,
            "email": "d***@example.test",
            "group": "default",
            "quota": 0,
            "used_quota": 0,
            "request_count": 0,
            "permissions": {
                "sidebar_settings": true,
                "sidebar_modules": {},
                "admin_permissions": {}
            }
        }
    }
}

🟠409

🟠429

完成密码登录的 2FA 验证

本地契约说明#

请求参数

请求示例代码

返回响应

本地契约说明