---
title: "Login"
method: POST
path: "/auth/login"
---

# Login

`POST /auth/login`

## Request

- Base URL: `https://api.twtapi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.twtapi.com/auth/login`
- Auth: none declared

账号密码登录，成功后下发 session cookie。

主流程：
  1. 按 email 读登录失败计数（Redis），决定本次是否必须带图形验证码；
  2. 校验密码；
  3. 校验账号状态（冻结即拒）；
  4. 跑一次登录风控，风控要求验证码而请求没带则中断；
  5. 清空失败计数，创建新 session 并种 cookie。

返回：成功回传 user_id / api_key / mcp_key；失败返回带 sub_code 的 error
（40111 密码错、40301 账号冻结、40002 需要验证码）。
副作用：写 Redis（失败计数、session）、写库（last_lang、风控事件）。

安全设计：失败计数达到 CAPTCHA_FAIL_THRESHOLD 后强制人机校验；
注意计数是按 email 而非 IP 维度，属于「宁可误伤也要挡住撞库」的取舍。

## Query parameters

- `lang` string

## Request body

- LoginRequest: 登录请求。captcha 可选：风控判定需要时才要求前端带图形验证码。
  - `email` string, required
  - `password` string, required
  - `captcha` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/twtapi/apis/twtapi-backend.md) · [All operations](https://skmtc.dev/twtapi/apis/twtapi-backend/llms.txt) · [OpenAPI document](https://skmtc.dev/twtapi/apis/twtapi-backend/revisions/5295976febaf?raw)