基础认证 (Base Token)

在正式开始接入系统并调用各项业务 API 之前，我们需要先完成基础的认证准备工作。

准备工作

请确保您已经从系统管理员或开发者控制台获取了以下凭证：

• API Key (作为您的公钥/识别码)
• Secret Key (作为您加密数据的私钥，长度为 32 位)

这两项凭证是应用接入的唯一身份标识，请妥善保管，绝不能泄露至前端公共代码或第三方仓库中。

---

获取 Base Token 接口

系统中的所有核心登入和数据操作都需要携带 baseToken。它是后续与平台建立信任的钥匙。

接口详情

• 请求路径: POST /client/baseToken
• 请求格式: multipart/form-data
• 参数说明:

字段名	类型	必填	描述
key	String	是	经过特殊加密和拼接的凭证字符串，格式为 加密时间戳.API_Key

---

加密规则与格式

为了保证请求的安全性并防止重放攻击，你需要对“当前的时间戳”进行加密，并与你的 API Key 进行拼接。

1. 核心加密要求

• 算法: AES-256-CBC
• 填充模式: PKCS7
• 密钥 (Key): 就是您的 Secret Key (固定 32 字节)
• 初始向量 (IV): 取 Secret Key 的前 16 个字符
• 加密内容 (Plaintext): 当前时间的 Unix 时间戳（精确到秒，字符串格式）。注：误差不能超过正负 5 分钟。

2. 拼接规则

将上述 AES 加密出来的结果转换为 Base64 字符串，并在末尾加上一个英文句号 .，最后接上您的 API Key。

最终传给后端的 key 格式如下：

<Base64加密字符串>.<您的_API_Key>

例如：
WfTEFb5WYaHQVBpUI+YIxQ==.3b8043ce33f248b98a7b501fab206c98

---

代码接入示例 (Node.js / 前端)

以下提供使用标准 crypto-js 库生成合法 key 的示例：

import CryptoJS from 'crypto-js';

// 1. 准备您的凭证
const API_KEY = "your_actual_api_key_here";
const SECRET_KEY = "your_actual_secret_key_here"; // 必须是 32 位

// 2. 初始化密钥和 IV
const keyObj = CryptoJS.enc.Utf8.parse(SECRET_KEY);
const ivObj = CryptoJS.enc.Utf8.parse(SECRET_KEY.substring(0, 16));

// 3. 获取当前时间戳 (秒)，并转为字符串
const timestamp = Math.floor(Date.now() / 1000).toString();

// 4. 执行 AES-256-CBC 加密
const encrypted = CryptoJS.AES.encrypt(timestamp, keyObj, {
    iv: ivObj,
    mode: CryptoJS.mode.CBC,
    padding: CryptoJS.pad.Pkcs7
});

// 5. 生成 Base64 字符串并拼接
const base64Str = encrypted.toString();
const finalKeyString = `${base64Str}.${API_KEY}`;

// 6. 将 finalKeyString 作为表单 `key` 字段提交到后端
console.log("生成的 Key:", finalKeyString);

---

响应解析与使用

请求成功后，后端将返回如下结构：

{
  "code": 0,
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "msg": "success"
}

解析 Base Token

返回的 baseToken 是一个标准的 JWT (JSON Web Token)。

• 它的 Payload 采用自包含设计，解析后包含您的核心业务信息以及过期时间 (exp)。
• 在后续的所有核心 API 调用中，请将其作为身份凭证放入请求头中（例如：Authorization: Bearer <baseToken>，具体视各业务接口规范而定）。

解密查看与验签

即使不写代码，您也可以将获取到的 baseToken 粘贴到 jwt.io，立刻看到里面签发的真实内容和有效时长。由于系统采用了您的独立秘钥进行签发，如果您想验证该 JWT 的合法性，可以在 jwt.io 右下角的 Signature 区域填入您的 Secret Key 进行验证。