twtapi-com Auth API

openapi: 3.2.0
info:
  title: TwtAPI Backend Auth API
  description: API proxy & billing platform for Twitter/RapidAPI
  version: 0.1.0
tags:
- name: Auth
paths:
  /auth/oauth/google/start:
    get:
      summary: Google Oauth Start
      description: 'OAuth 第一步：生成 state 并 302 跳转到 Google 授权页。


        参数 lang：用户界面语言；returnUrl：登录成功后希望回到的前端站内路径。


        为什么要用 state：回调请求是从 Google 域名跳回来的，浏览器带不回本站的任何

        上下文，所以把「语言 + 回跳地址」连同随机 state 一起存进 Redis，回调时凭 state

        取回。state 同时充当 CSRF 令牌，防止别人伪造回调把攻击者的 Google 账号

        绑到受害者会话上。

        返回：RedirectResponse 到 Google 授权页；未配置 Google 凭证时返回 error(500)。

        副作用：写 Redis（state 记录，TTL 10 分钟）。'
      operationId: google_oauth_start_auth_oauth_google_start_get
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      - name: returnUrl
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Returnurl
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/oauth/google/callback:
    get:
      summary: Google Oauth Callback
      description: 'OAuth 第二步：处理 Google 回调，换用户信息、建会话，再 302 回前端。


        主流程：校验 state（一次性）-> 用 code 换 userinfo -> 校验邮箱已验证

        -> 绑定/创建本站用户 -> 风控记录 -> 建 session 并种 cookie -> 跳回 return_url。


        参数 code/state 来自 Google 回调 query；error_description 是用户在 Google 侧

        点了「拒绝授权」时 Google 带回来的原因。

        返回：成功是带 Set-Cookie 的 302；任何失败都 302 回登录页并附 oauth_error 文案。

        —— 这里刻意不向外抛 5xx，因为回调是浏览器直接导航，返回 JSON 报错用户看不懂。

        副作用：写库（用户/绑定/last_lang/风控事件）、写 Redis（session）、外部 HTTP 请求。


        注意：整个流程被一个宽泛的 try/except 包住，异常只记日志、对外统一提示

        "Google login failed"，避免把栈信息或 token 细节泄露到 URL 上。'
      operationId: google_oauth_callback_auth_oauth_google_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: State
      - name: error_description
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/sendEmailCode:
    post:
      summary: Send Email Code
      description: '发送注册邮箱验证码。同一邮箱 60 秒内只能请求一次；验证码 5 分钟内有效。


        返回：成功是 success；命中冷却返回 40008；邮箱已注册返回 40003；发信失败返回 50011。

        副作用：写 Redis（验证码 + 冷却键）、向外部邮件服务发起发送请求。


        顺序上先写 Redis 再发信：这样即使发信失败，冷却键也已经落下，

        用户必须等冷却结束才能重试 —— 用「可能多等 60 秒」换「不会因发信故障被无限刷」。

        另外，对已注册邮箱直接返回 email_exists，等于暴露了「该邮箱是否已注册」，

        这是产品上为了方便用户（提示去登录）而接受的取舍。'
      operationId: send_email_code_auth_sendEmailCode_post
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailCodeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/register:
    post:
      summary: Register
      description: '注册账号：校验密码长度 -> 图形验证码 -> 邮箱验证码 -> 建号并记录风控。


        返回：成功时回传 user_id / api_key / mcp_key；各类失败返回带 sub_code 的 error。

        副作用：写库（建 User、last_lang、风控事件/画像）、写 Redis（消费验证码）。

        注意：注册成功后不会自动登录、不下发 session cookie，前端需要再调一次 /login。'
      operationId: register_auth_register_post
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/login:
    post:
      summary: Login
      description: '账号密码登录，成功后下发 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 维度，属于「宁可误伤也要挡住撞库」的取舍。'
      operationId: login_auth_login_post
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/getInfo:
    get:
      summary: Get Info
      description: '前端启动时拉取当前登录态，未登录也会给一个空 session。


        返回：已登录 -> {is_login: True, user_id, email, api_key, is_admin}；

        未登录 -> {is_login: False, is_admin: False}。

        副作用：写 Redis（未登录时新建空 session；stage_user_last_lang 是暂存，稍后批量落库）。'
      operationId: get_info_auth_getInfo_get
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/logout:
    post:
      summary: Logout
      description: '退出登录：删除 Redis 中的会话并清掉 cookie。


        返回：success(退出成功文案)。

        副作用：写 Redis（删 session）。

        注意：只失效当前这一个 session_id，用户在其他设备/浏览器的登录态不受影响。'
      operationId: logout_auth_logout_post
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/checkCaptchaRequired:
    post:
      summary: Check Captcha Required
      description: '供前端在提交登录前询问「这次要不要显示图形验证码」。


        判定来源有两处：Redis 登录失败计数（先看，便宜），以及风控画像里的历史风险标记。

        返回：success(data={"captcha_required": bool})。

        副作用：只读（风控画像是读缓存/DB）。'
      operationId: check_captcha_required_auth_checkCaptchaRequired_post
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckCaptchaRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/sendResetPasswordEmail:
    post:
      summary: Send Reset Password Email
      description: '发起找回密码：校验图形验证码后生成一次性重置 token。


        返回：success(reset_email_sent)；邮箱不存在返回 40401。

        副作用：写 Redis（reset_token:{token} -> user_id，TTL 1800 秒），并写日志。


        注意：目前真正的邮件通道还没接上，token 只打在日志里（见下方 TODO），

        也就是说这个接口现在只能靠运维从日志里取链接；同时「邮箱不存在返回 404」

        同样会暴露账号是否注册。'
      operationId: send_reset_password_email_auth_sendResetPasswordEmail_post
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendResetEmailRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/resetPassword:
    post:
      summary: Reset Password
      description: '凭邮件里的 token 重置密码（无需登录）。


        流程：密码长度 -> 图形验证码 -> 校验 token -> 改密 -> 删除 token。

        返回：成功 success；密码过短 40005；验证码错 40001；token 无效 40006。

        副作用：写库（更新 password_hash）、写 Redis（消费 token）。


        安全性：token 用后即删、30 分钟过期，且必须配合图形验证码提交，

        因此光拿到 token 还不能重置；但重置成功后并不会踢掉已有的登录会话。'
      operationId: reset_password_auth_resetPassword_post
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/changePassword:
    post:
      summary: Change Password
      description: '已登录用户改密：先验旧密码，再写入新密码。


        Logged-in user: verify current password, then set new password.


        参数 session 由 require_login 注入，未登录会直接 401（sub_code=40101）。

        返回：成功 success；新密码过短 40005；用户不存在 40402；旧密码错 40111。

        副作用：写库（更新 password_hash）—— 用户身份取 session 而非请求体，避免越权改他人密码。'
      operationId: change_password_auth_changePassword_post
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
  /auth/order:
    post:
      summary: Create Order
      description: '创建订单（下单入口），只落 pending 单，不涉及任何实际收款。


        已登录则关联 user_id，未登录（匿名）也能下单，此时 user_id 为空。

        Price comes from the plans table.


        价格与计费方式一律以后端 plans 表为准，前端传来的 plan_type/plan_name 只用来定位套餐，

        杜绝篡改价格。


        主流程：

        1. 按 plan_type + plan_name 查启用中的套餐，查不到即拒（40007）；

        2. 解析套餐 features（展示用快照）；

        3. 决定计费方式与成交价：订阅单且订阅价 > 0 用 subscription_price，否则用 price；

        4. 0 元单一律降级成一次性（不得成为订阅）；

        5. api 类型的免费套餐不允许下单（注册时已赠送，兼容旧前端）；

        6. 登录用户领 0 元试用：先过风控 deny_free_trial，再加行锁做重复领取检查；

        7. 登录用户买付费订阅：加行锁做重复下单检查；

        8. 落一张 pending 单，expires_at = 现在 + ORDER_PENDING_TIMEOUT_MINUTES。


        返回：success(data={order_id, order_no, status})；各类重复/非法下单返回带 sub_code 的 error。

        副作用：写库（orders、风控事件/画像）；锁行会占用数据库连接直到事务结束。


        并发说明：查询与插入之间不是原子的，靠 _for_update 锁住 users 行把同一用户的

        下单流程串行化；匿名（user_id 为空）路径拿不到任何锁，因此不享受这层保护。'
      operationId: create_order_auth_order_post
      parameters:
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Auth
components:
  schemas:
    ResetPasswordRequest:
      properties:
        token:
          type: string
          title: Token
        password:
          type: string
          title: Password
        captcha:
          type: string
          title: Captcha
      type: object
      required:
      - token
      - password
      - captcha
      title: ResetPasswordRequest
      description: '凭邮件里的 token 重置密码。


        token 由 generate_reset_token() 生成、存于 Redis 且一次性使用；

        这里只承载它，有效性由 auth_service 判断。'
    ChangePasswordRequest:
      properties:
        current_password:
          type: string
          title: Current Password
        new_password:
          type: string
          title: New Password
      type: object
      required:
      - current_password
      - new_password
      title: ChangePasswordRequest
      description: 'Logged-in user change password: current + new.


        中文：已登录用户改密。要求提供原密码，因此此接口调用前

        必须先通过会话鉴权（require_login）。'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LoginRequest:
      properties:
        email:
          type: string
          title: Email
        password:
          type: string
          title: Password
        captcha:
          anyOf:
          - type: string
          - type: 'null'
          title: Captcha
      type: object
      required:
      - email
      - password
      title: LoginRequest
      description: 登录请求。captcha 可选：风控判定需要时才要求前端带图形验证码。
    RegisterRequest:
      properties:
        email:
          type: string
          title: Email
        password:
          type: string
          title: Password
        captcha:
          type: string
          title: Captcha
        email_code:
          type: string
          title: Email Code
      type: object
      required:
      - email
      - password
      - captcha
      - email_code
      title: RegisterRequest
      description: 注册请求。图形验证码 + 邮箱验证码双重校验，两者缺一不可。
    CreateOrderRequest:
      properties:
        plan_type:
          type: string
          title: Plan Type
        plan_name:
          type: string
          title: Plan Name
        price:
          type: number
          title: Price
        currency:
          type: string
          title: Currency
          default: usd
        features:
          items:
            type: string
          type: array
          title: Features
          default: []
        payment_method:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Method
        billing_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Billing Mode
      type: object
      required:
      - plan_type
      - plan_name
      - price
      title: CreateOrderRequest
      description: '创建订单。


        安全提示：price 由客户端提交，服务端必须与 Plan 表的值比对后

        再落库，不能直接采信。'
    CheckCaptchaRequest:
      properties:
        email:
          type: string
          title: Email
      type: object
      required:
      - email
      title: CheckCaptchaRequest
      description: 按邮箱探测「本次登录是否需要图形验证码」，用于前端决定是否展示输入框。
    SendEmailCodeRequest:
      properties:
        email:
          type: string
          title: Email
      type: object
      required:
      - email
      title: SendEmailCodeRequest
      description: 请求发送邮箱验证码。发送频率受 EMAIL_CODE_COOLDOWN 限制。
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SendResetEmailRequest:
      properties:
        email:
          type: string
          title: Email
        captcha:
          type: string
          title: Captcha
      type: object
      required:
      - email
      - captcha
      title: SendResetEmailRequest
      description: 发送重置密码邮件，同样需要图形验证码防刷。