❤️❤️❤️❤️❤️❤️ 我们已经正式推出微信小程序，在微信中搜索 TrendForge Pro 即可使用小程序，如果使用 Telegram 请搜索 trendforge_tg ❤️❤️❤️❤️❤️❤️

标题

JWT 解码 API

JSON Web Token 解码接口。拆解 JWT 三段，输出 header / payload，归一化常见时间声明（exp / nbf / iat），并可选用 HMAC secret 校验签名。

鉴权

所有接口均需在请求头中携带访问令牌：

Authorization: Bearer tf_xxxxxxxxxxxxxxxx

令牌在 用户设置 → 访问令牌 页面创建，创建时需勾选对应权限：

权限 说明
read:tools_jwt 调用 JWT 解码接口

频率限制

范围 上限
单用户 / 单分钟 30 次
单用户 / 单日 1000 次

超限返回 429。

接口列表

1. 解码 JWT

POST /api/tools/jwt/decode

所需权限：read:tools_jwt

解码 JWT 并归一化时间字段；提供 secret 时校验 HMAC 签名。

请求体（JSON）

参数 类型 必填 说明
token string 是 三段式 base64url 编码的 JWT，形如 header.payload.signature
secret string 否 HMAC 共享密钥。仅支持 HS256 / HS384 / HS512；留空则不校验签名

返回值

{
  "success": true,
  "data": {
    "header": {
      "alg": "HS256",
      "typ": "JWT"
    },
    "payload": {
      "sub": "tester",
      "iat": 1780300057,
      "exp": 1780303657,
      "scope": ["read", "write"]
    },
    "claims": {
      "exp_iso": "2026-06-01T08:47:37.000Z",
      "nbf_iso": null,
      "iat_iso": "2026-06-01T07:47:37.000Z",
      "is_expired": false,
      "is_not_yet_valid": null,
      "age_seconds": 0
    },
    "signature": {
      "valid": true,
      "note": null
    }
  }
}

字段说明

顶层

字段 类型 说明
header object JWT 第一段解码后的 JSON，字段原样回传
payload object JWT 第二段解码后的 JSON，字段原样回传

claims — 时间声明归一化

字段 类型 说明
exp_iso string exp 字段（Unix 秒）转 ISO；payload 无 exp 时为 null
nbf_iso string nbf 字段转 ISO
iat_iso string iat 字段转 ISO
is_expired boolean true 表示 exp < now；无 exp 时为 null
is_not_yet_valid boolean true 表示 nbf > now；无 nbf 时为 null
age_seconds integer now - iat（秒），可为负

signature — 签名校验结果

场景 valid note
提供了 secret，HS256 / 384 / 512 校验通过 true null
提供了 secret，HS256 / 384 / 512 校验失败 false "invalid signature" 等
未提供 secret null "secret_not_provided"
Header alg 为 RS256 / ES256 / PS256 / EdDSA 等非对称算法 null "unsupported_alg_asymmetric"
Header alg 是未识别字符串 null "unsupported_alg"

非对称算法需要公钥而非 secret，本接口暂不支持，后续会以 JWK / PEM 形式开放。

示例

# 仅解码，不校验签名
curl -X POST "https://trendforge.devlive.top/api/tools/jwt/decode" \
  -H "Authorization: Bearer tf_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0ZXIifQ.signature"}'

# 解码并校验 HMAC 签名
curl -X POST "https://trendforge.devlive.top/api/tools/jwt/decode" \
  -H "Authorization: Bearer tf_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0ZXIifQ.signature",
    "secret": "my-shared-secret"
  }'

错误响应

所有错误均返回 JSON 格式：

{
  "success": false,
  "code": 400,
  "message": "JWT 格式不正确"
}
HTTP 状态码 code 原因
400 400 token 缺失 / 不是三段式 / 段内 base64 / JSON 无法解析
401 401 未携带令牌或令牌无效
403 403 令牌缺少 read:tools_jwt 权限
429 429 命中分钟级或日级频率限制
500 500 服务器内部错误

数据说明

  • 单次调用为内存计算，不持久化、不缓存、不上报第三方
  • secret 仅在服务端用于校验，不写日志、不回显
  • 解码不等于校验：只有同时提供正确 secret 并 signature.valid === true，才能信任 payload
  • payload 可能包含敏感字段（email / sub / 内部 ID），调用方需自行决定是否回显
  • 非对称签名（如 OAuth provider 颁发的 RS256 token）请通过 provider 的 JWKS endpoint 校验，本接口不替代该流程
  • 同一令牌的频率配额与同一登录会话共享
助手