认证 API

NOLUX 采用 JWT（JSON Web Token）双令牌机制进行身份认证。本文档介绍认证相关的 API 接口。

认证机制

双令牌设计

令牌	有效期	用途
Access Token	30 分钟	用于 API 请求认证
Refresh Token	7 天	用于刷新 Access Token

认证流程

用户登录
  │
  ▼
获取 Access Token + Refresh Token
  │
  ▼
使用 Access Token 调用 API
  │
  ▼
Access Token 过期（30 分钟后）
  │
  ▼
使用 Refresh Token 获取新的 Access Token
  │
  ▼
Refresh Token 过期（7 天后）
  │
  ▼
需要重新登录

登录

POST /api/v1/auth/login

用户名密码登录，获取令牌对。

请求体：

{
  "username": "zhangsan@example.com",
  "password": "your_password"
}

成功响应（200）：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer",
    "expires_in": 1800,
    "user": {
      "id": "uuid-string",
      "username": "zhangsan@example.com",
      "display_name": "张三",
      "roles": ["operator"],
      "tenant_id": "uuid-string",
      "tenant_name": "品牌示例"
    }
  }
}

错误响应：

状态码	错误码	说明
401	AUTH_001	用户名或密码错误
403	AUTH_002	账号已被禁用
403	TENANT_002	所属租户已暂停

示例：

curl -X POST "https://api.nolux.cn/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "zhangsan@example.com", "password": "your_password"}'

刷新令牌

POST /api/v1/auth/refresh

使用 Refresh Token 获取新的 Access Token。

请求体：

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

成功响应（200）：

{
  "code": 200,
  "message": "刷新成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...(新)",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...(新)",
    "token_type": "bearer",
    "expires_in": 1800
  }
}

错误响应：

状态码	错误码	说明
401	AUTH_003	Refresh Token 已过期
401	AUTH_004	Refresh Token 无效或已被撤销

安全提示

每次刷新时，旧的 Refresh Token 会被自动撤销（Rotation 机制），新的 Refresh Token 会随 Access Token 一起返回。这能有效防止 Token 泄露后的持续利用。

登出

POST /api/v1/auth/logout

主动登出，撤销当前令牌对。

请求头：

Authorization: Bearer {access_token}

请求体：

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

成功响应（200）：

{
  "code": 200,
  "message": "登出成功"
}

获取当前用户信息

GET /api/v1/auth/me

获取当前认证用户的详细信息。

请求头：

Authorization: Bearer {access_token}

成功响应（200）：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "uuid-string",
    "username": "zhangsan@example.com",
    "display_name": "张三",
    "avatar_url": "https://oss.nolux.cn/avatars/xxx.jpg",
    "roles": [
      {
        "role": "operator",
        "org_node_id": "uuid-string",
        "org_node_name": "天猫运营组"
      }
    ],
    "tenant": {
      "id": "uuid-string",
      "name": "品牌示例",
      "slug": "brand-example",
      "subscription_tier": "growth"
    },
    "permissions": [
      "product:read",
      "order:read",
      "campaign:manage",
      "report:export"
    ],
    "last_login_at": "2026-03-14T09:00:00Z",
    "created_at": "2026-01-15T12:00:00Z"
  }
}

修改密码

PUT /api/v1/auth/password

修改当前用户密码。

请求体：

{
  "current_password": "old_password",
  "new_password": "new_secure_password",
  "confirm_password": "new_secure_password"
}

成功响应（200）：

{
  "code": 200,
  "message": "密码修改成功，请重新登录"
}

密码规则：

• 最少 8 个字符
• 必须包含大小写字母
• 必须包含数字
• 不能与最近 3 次密码相同

租户上下文切换

对于拥有多租户访问权限的用户（如超级管理员或跨租户代运营），可通过以下方式切换租户上下文：

POST /api/v1/auth/switch-tenant

请求体：

{
  "tenant_id": "uuid-of-target-tenant"
}

成功响应（200）：

{
  "code": 200,
  "message": "租户切换成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...(新，包含新租户上下文)",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...(新)",
    "tenant": {
      "id": "uuid-of-target-tenant",
      "name": "目标租户名称",
      "slug": "target-tenant"
    }
  }
}

JWT Token 结构

Access Token 的 Payload 包含以下声明（Claims）：

{
  "sub": "user-uuid",
  "tenant_id": "tenant-uuid",
  "roles": ["operator"],
  "exp": 1710412200,
  "iat": 1710410400,
  "jti": "unique-token-id"
}

字段	说明
sub	用户 ID
tenant_id	当前租户 ID
roles	用户角色列表
exp	过期时间（Unix 时间戳）
iat	签发时间
jti	Token 唯一标识（用于撤销）

安全要求

• 所有 API 请求必须通过 HTTPS
• 请勿在客户端明文存储 Token，建议使用 httpOnly Cookie 或安全存储
• Token 泄露后应立即调用登出接口撤销

---

相关文档

• API 概览 — 通用请求规范
• 系统架构 — 认证中间件详解