#JWT Token 生成

本系统 API 使用 Bearer Token 进行身份认证。

如果你需要获取某个用户的 JWT Token，推荐做法是：

1. 先在管理员页面的 系统配置 -> API密钥 中创建或获取 API key
2. 使用该 API key 调用 yiaskAuth:issueUserToken 接口，为目标用户签发可直接使用的 JWT Token

#前置条件

• 已有管理员页面 系统配置 -> API密钥 中创建的 API key
• 已知目标用户的 userId 或 username

#第一步：获取 API key

使用管理员账号登录系统后，进入：

系统配置 -> API密钥

创建或获取一个 API key。该接口仅允许使用这里生成的 API key 调用，不能使用普通用户登录 token 调用。

创建完成后，你会得到一个 Bearer Token。后续调用 yiaskAuth:issueUserToken 时，Authorization 头里填的就是这个 API key。

API key 的角色范围规则：

• root 角色 API key 可以为任意用户签发 token。
• admin 角色 API key 可以为不包含 root 角色的用户签发 token。
• 其他角色 API key 只能为角色集合完全等于该 API key 角色的用户签发 token。

#第二步：调用 yiaskAuth:issueUserToken

该接口会按当前 token policy 为目标用户生成一个标准 session token，返回的 token 可直接用于后续 API 调用。

接口地址：

POST /api/yiaskAuth:issueUserToken

请求头：

Authorization: Bearer <API_KEY>
Content-Type: application/json

请求体：

userId 和 username 二选一，不能同时提供或同时不提供。

{
  "userId": 2
}

或使用 username：

{
  "username": "alice"
}

#cURL 示例

使用 userId：

curl 'http://localhost:13000/api/yiaskAuth:issueUserToken' \
  -X POST \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "userId": 2
  }'

使用 username：

curl 'http://localhost:13000/api/yiaskAuth:issueUserToken' \
  -X POST \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "username": "alice"
  }'

#返回示例

{
  "token": "<USER_JWT_TOKEN>",
  "jti": "8ef7dc1d-4ddb-4c55-b6f5-0dd6dc28b6b4",
  "expiresAt": "2026-03-27T08:00:00.000Z",
  "user": {
    "id": 2,
    "username": "alice",
    "email": "alice@example.com",
    "nickname": "Alice"
  }
}

#返回字段说明

#第三步：使用返回的用户 Token

在后续 API 请求中，将上一步返回的 token 放入 Authorization 请求头：

Authorization: Bearer <USER_JWT_TOKEN>

示例：

curl 'http://localhost:13000/api/auth:check' \
  -H 'Authorization: Bearer <USER_JWT_TOKEN>' \
  -H 'X-SPACES: default'

#常见错误

#1. 返回 403

说明当前调用者没有使用有效的 API key，或 API key 的角色范围不允许为该目标用户签发 token。

#2. 返回 404

说明传入的 userId 或 username 对应的用户不存在。

#3. 返回 400 - 参数错误

可能的原因：

• 同时提供了 userId 和 username
• 两个参数都没有提供
• userId 不是正整数
• username 为空字符串或非字符串类型

#4. 注销时报时间格式错误

不要自己手工拼 JWT Payload，也不要自己用 APP_KEY 加密。

如果手工生成的 Token 缺少 jti、exp 等字段，后续调用 auth:signOut 时可能出现时间字段错误。请统一使用 yiaskAuth:issueUserToken 接口签发。

#安全建议

1. 妥善保管 API key，不要提交到代码仓库或暴露到前端。
2. API key 只用于服务端调用，不要直接发给终端用户。
3. 生产环境务必使用 HTTPS。
4. 建议定期轮换 API 密钥，并清理不再使用的旧密钥。
5. 管理员账号下，进入“系统配置 - 安全性 - Token策略”，配置 Token 过期时间等安全参数（如下图所示）。建议缩短 Token 过期时间，例如 1 小时。