twtapi-com Auth API
The Auth API from twtapi-com — 12 operation(s) for auth.
The Auth API from twtapi-com — 12 operation(s) for auth.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/twtapi-com:twtapi-com-auth-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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: 发送重置密码邮件,同样需要图形验证码防刷。