认证接口 - TaskNeo

POST /auth/register

发送验证邮件以开始注册。这是两步注册流程的第 1 步。

管理员可以关闭注册。若 auth.registration_open 为 false，此接口返回 403。每个地址每 24 小时最多发送 5 封邮件。

Request body

string

required

要注册的邮箱地址。验证链接会发送到该地址。

captchaToken

string

验证码挑战成功后返回的令牌。仅当部署已启用 CAPTCHA 时需要提供。

Responses

message

string

确认验证邮件已发送。

Error codes

状态	何时发生
`400 Bad Request`	已启用 CAPTCHA，但未提供 `captchaToken`。
`403 Forbidden`	管理员已关闭注册。
`403 Forbidden`	CAPTCHA 校验失败。
`409 Conflict`	邮箱地址已注册。
`429 Too Many Requests`	已超过速率限制（每个地址 24 小时 5 封）。
`503 Service Unavailable`	CAPTCHA 已启用但服务不可用或未正确配置。

curl -X POST https://api.yourdomain.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "captchaToken": "cap-token-from-widget"
  }'

POST /auth/register/complete

使用验证邮件中的令牌完成注册。这是注册流程的第 2 步。

该令牌只能使用一次，并会在 1 小时后过期。成功后，系统会自动为新用户创建个人班级，并返回 JWT，使用户立即登录。

Request body

token

string

required

邮箱链接中的验证令牌。

password

string

required

账户密码。至少 8 个字符。

nickname

string

显示名称。若省略，界面会使用用户的邮箱地址作为默认显示名。

schoolId

string

要关联到此账户的学校 UUID。若提供，则必须填写 studentId。

studentId

string

学号。提供 schoolId 时必填，且在该学校内必须唯一。

timezone

string

default:"UTC"

IANA 时区标识符（例如 America/New_York）。用于按用户本地时间显示截止日期。

Response — 201 Created

token

string

required

JWT Bearer 令牌，有效期 7 天。

user

object

required

Show properties

string

required

新用户 UUID。

string

required

已注册的邮箱地址。

nickname

string

显示名称，若未设置则为 null。

schoolId

string

关联学校 UUID，或 null。

schoolName

string

学校显示名称，或 null。

studentId

string

学号，或 null。

timezone

string

required

IANA 时区标识符。

isActive

boolean

required

账户是否处于启用状态。

createdAt

string

required

ISO 8601 UTC 时间戳。

Error codes

状态	何时发生
`400 Bad Request`	令牌无效、已过期，或验证失败。

curl -X POST https://api.yourdomain.com/auth/register/complete \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abc123verificationtoken",
    "password": "securepassword",
    "nickname": "Alex",
    "timezone": "America/New_York"
  }'

使用邮箱和密码登录。返回 JWT 和用户资料。 Request body

string

required

已注册的邮箱地址。

password

string

required

账户密码。

Response — 200 OK

token

string

required

JWT Bearer 令牌，有效期 7 天。

user

object

required

Show properties

string

required

用户 UUID。

string

required

邮箱地址。

nickname

string

显示名称，或 null。

schoolId

string

学校 UUID，或 null。

schoolName

string

学校名称，或 null。

studentId

string

学号，或 null。

timezone

string

required

IANA 时区标识符。

isActive

boolean

required

账户状态。

createdAt

string

required

ISO 8601 UTC 时间戳。

Error codes

状态	何时发生
`401 Unauthorized`	Email or password is incorrect.
`403 Forbidden`	Account has been deactivated.

curl -X POST https://api.yourdomain.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "yourpassword"
  }'

POST /users/me/email/change

向新邮箱地址发送变更验证邮件。你需要携带登录令牌。

如果部署启用了 CAPTCHA，你必须提供 captchaToken。该接口同样受邮件发送限流保护。

Request body

string

required

你要更换到的新邮箱地址。

captchaToken

string

验证码挑战成功后返回的令牌。仅当部署已启用 CAPTCHA 时需要提供。

Response — 200 OK

message

string

确认验证邮件已发送。

Error codes

状态	何时发生
`400 Bad Request`	已启用 CAPTCHA，但未提供 `captchaToken`。
`401 Unauthorized`	缺少或无效的登录令牌。
`403 Forbidden`	CAPTCHA 校验失败。
`409 Conflict`	该邮箱已被其他账户使用。
`429 Too Many Requests`	已超过邮件发送速率限制。
`503 Service Unavailable`	CAPTCHA 已启用但服务不可用或未正确配置。

curl -X POST https://api.yourdomain.com/users/me/email/change \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new@example.com",
    "captchaToken": "cap-token-from-widget"
  }'

POST /users/me/email/confirm

使用邮件中的令牌确认邮箱变更。你需要携带登录令牌。 Request body

token

string

required

邮箱变更确认链接中的令牌。

Response — 200 OK 返回更新后的用户对象。 Error codes

状态	何时发生
`400 Bad Request`	令牌无效或已过期。
`401 Unauthorized`	缺少或无效的登录令牌。
`409 Conflict`	目标邮箱已被其他账户使用。

POST /auth/forgot-password

请求密码重置邮件。为防止邮箱枚举，该接口始终返回 200 - 无论该地址是否已注册，响应都相同。

每个地址每 24 小时最多发送 5 封邮件。重置链接包含一个只能使用一次、且 1 小时后过期的令牌。

Request body

string

required

与账户关联的邮箱地址。

Response — 200 OK

message

string

通用确认消息。

Error codes

状态	何时发生
`429 Too Many Requests`	已超过速率限制。

curl -X POST https://api.yourdomain.com/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

POST /auth/reset-password

使用重置邮件中的令牌设置新密码。返回 JWT，使用户在重置后立即登录。

该令牌只能使用一次，并会在 1 小时后过期。

Request body

token

string

required

邮件链接中的重置令牌。

password

string

required

新密码。至少 8 个字符。

Response — 200 OK 返回 { token, user } - 结构与 POST /auth/login 相同。 Error codes

状态	何时发生
`400 Bad Request`	Token is invalid or expired.

curl -X POST https://api.yourdomain.com/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abc123resettoken",
    "password": "newsecurepassword"
  }'

GET /auth/verify-token

检查验证令牌是否仍然有效，并返回其关联的邮箱地址。前端会用它在显示注册或密码重置表单之前验证令牌。 Query parameters

token

string

required

要验证的令牌。

purpose

string

required

令牌用途。取值之一：REGISTRATION、PASSWORD_RESET。

Response — 200 OK

valid

boolean

若令牌存在且未过期则为 true，否则为 false。

string

与该令牌关联的邮箱地址。仅在 valid 为 true 时存在。

curl "https://api.yourdomain.com/auth/verify-token?token=abc123&purpose=REGISTRATION"

概览

接口

​POST /auth/register

​POST /auth/register/complete

​POST /auth/login

​POST /users/me/email/change

​POST /users/me/email/confirm

​POST /auth/forgot-password

​POST /auth/reset-password

​GET /auth/verify-token

POST /auth/register

POST /auth/register/complete

POST /auth/login

POST /users/me/email/change

POST /users/me/email/confirm

POST /auth/forgot-password

POST /auth/reset-password

GET /auth/verify-token