认证接口

认证接口

HeteroFlow V2 的认证接口提供用户注册、登录、Token 管理等完整的认证 API。所有接口遵循 RESTful 规范，返回 JSON 格式数据。

接口概览

---

用户注册

注册新用户账号。

请求

POST /api/v1/auth/register
Content-Type: application/json

{
  "username": "newuser",
  "password": "SecurePass123!",
  "email": "user@example.com"
}

响应

成功 (201):

{
  "id": 2,
  "username": "newuser",
  "role": "user",
  "email": "user@example.com",
  "created_at": "2026-05-20T10:00:00Z"
}

失败 - 用户名已存在 (400):

{
  "error": "username already exists",
  "code": 40001
}

失败 - 参数校验失败 (400):

{
  "error": "username must be 3-20 characters",
  "code": 40002
}

---

用户登录

使用用户名和密码登录，获取 JWT Token。

请求

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}

响应

成功 (200):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6ImFkbWluIiwicm9sZSI6ImFkbWluIiwiZXhwIjoxNzE2MjQ5NjAwLCJpYXQiOjE3MTYxNjMyMDB9.xxxxx",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.yyyyy",
  "expires_in": 86400,
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "email": "admin@heteroflow.io"
  }
}

失败 - 凭证错误 (401):

{
  "error": "invalid username or password",
  "code": 40101
}

失败 - 账号被禁用 (403):

{
  "error": "account is disabled",
  "code": 40301
}

---

刷新 Token

使用 Refresh Token 获取新的 Access Token。

请求

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

响应

成功 (200):

{
  "token": "eyJhbGciOiJIUzI1NiIs...new_token",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...new_refresh",
  "expires_in": 86400
}

失败 - Token 无效 (401):

{
  "error": "invalid refresh token",
  "code": 40102
}

失败 - Token 已过期 (401):

{
  "error": "refresh token expired",
  "code": 40103
}

---

获取当前用户

获取当前登录用户的信息。

请求

GET /api/v1/auth/me
Authorization: Bearer <token>

响应

成功 (200):

{
  "id": 1,
  "username": "admin",
  "role": "admin",
  "email": "admin@heteroflow.io",
  "created_at": "2026-01-01T00:00:00Z",
  "last_login": "2026-05-20T10:00:00Z"
}

失败 - 未认证 (401):

{
  "error": "authentication required",
  "code": 40100
}

---

修改密码

修改当前用户的密码。

请求

PUT /api/v1/auth/password
Authorization: Bearer <token>
Content-Type: application/json

{
  "old_password": "admin123",
  "new_password": "NewSecurePass456!"
}

响应

成功 (200):

{
  "message": "password changed successfully"
}

失败 - 旧密码错误 (400):

{
  "error": "incorrect old password",
  "code": 40010
}

---

用户登出

登出当前用户，客户端应删除本地存储的 Token。

请求

POST /api/v1/auth/logout
Authorization: Bearer <token>

响应

成功 (200):

{
  "message": "logged out successfully"
}

> 注意: 服务端 JWT 为无状态设计，登出操作主要由客户端清除 Token 实现。如需服务端主动使 Token 失效，可配合 Token 黑名单机制。

错误码汇总