KeyHub API 文档

KeyHub 是一个简单易用的授权密钥管理系统，支持多项目管理、自定义密钥格式和客户端自助注册。

基础信息

  • Base URL: http://your-domain.com
  • 数据格式: application/json
  • 字符编码: UTF-8

🔐 验证接口

验证授权密钥是否在指定项目下有效。此接口用于客户端验证授权状态。

POST /api/verify

验证密钥在指定项目下的有效性

请求参数

参数名 类型 必填 说明
key String 是 授权密钥（可以是自动生成的 KH-XXXXXXXX-XXXXXXXX 格式或自定义密钥）
project_name String 是 项目名称（必须与密钥所属的项目名称一致）

请求示例

JSON 
{
    "key": "KH-A1B2C3D4-E5F6G7H8",
    "project_name": "Default Project"
}

响应参数

字段名 类型 说明
valid Boolean 验证结果（true 表示有效，false 表示无效）
message String 提示信息（中文）
project_name String 项目名称（仅在验证成功时返回）

响应示例

✅ 验证成功

状态码: 200 OK
JSON 
{
    "valid": true,
    "message": "验证通过",
    "project_name": "Default Project"
}

❌ 验证失败 - 密钥不存在

状态码: 404 Not Found
JSON 
{
    "valid": false,
    "message": "未找到该密钥在此项目下的授权"
}

❌ 验证失败 - 授权已禁用

状态码: 403 Forbidden
JSON 
{
    "valid": false,
    "message": "授权已禁用"
}

❌ 验证失败 - 参数错误

状态码: 400 Bad Request
JSON 
{
    "valid": false,
    "message": "密钥不能为空"
}
⚠️ 重要提示
  • 验证时必须同时提供 key 和 project_name 参数
  • 系统会验证密钥是否属于指定的项目，如果密钥存在但不属于该项目，将返回 404 错误
  • 只有密钥状态为"已激活"时才会验证通过

📝 注册接口

客户端用户自助注册接口，无需管理员权限。用于客户端首次注册授权密钥。

POST /api/register

客户端自助注册授权密钥（公开接口，无需认证）

请求参数

参数名 类型 必填 说明
key 或 custom_key String 是 授权密钥（支持任意格式，如手机号、邮箱、随机字符串等）
project_name String 是 项目名称（必须与后台创建的项目名称完全一致）
remarks String 否 备注信息（如"VIP用户"、"企业授权"等）

请求示例

JSON 
// 使用自动生成的密钥格式
{
    "key": "KH-A1B2C3D4-E5F6G7H8",
    "project_name": "Default Project",
    "remarks": "企业授权"
}

// 使用手机号作为密钥
{
    "key": "13800138000",
    "project_name": "Mobile App",
    "remarks": "VIP用户"
}

// 使用邮箱作为密钥
{
    "key": "user@example.com",
    "project_name": "Web Portal",
    "remarks": "个人用户"
}

响应示例

✅ 注册成功

状态码: 201 Created
JSON 
{
    "success": true,
    "key": "KH-A1B2C3D4-E5F6G7H8",
    "message": "注册成功"
}

❌ 注册失败 - 密钥已存在

状态码: 409 Conflict
JSON 
{
    "success": false,
    "message": "该密钥在此项目中已存在"
}

❌ 注册失败 - 项目不存在

状态码: 404 Not Found
JSON 
{
    "success": false,
    "message": "指定的项目不存在"
}

💡 使用说明

  • 此接口为公开接口，无需任何认证即可调用
  • 同一项目下，密钥必须唯一（不能重复注册）
  • 密钥格式完全自定义，可以是手机号、邮箱、随机字符串等任意格式
  • 注册成功后，密钥状态默认为"已激活"

🚀 集成指南

验证流程

  1. 获取密钥和项目名：从用户输入或配置文件中获取授权密钥和项目名称
  2. 调用验证接口：向 /api/verify 发送 POST 请求，包含 key 和 project_name
  3. 处理响应：根据返回的 valid 字段判断验证结果
  4. 错误处理：处理网络错误、超时等异常情况

最佳实践

  • 验证时机：建议在应用启动时验证一次，之后根据业务需要定期验证（如每天、每周）
  • 缓存结果：验证成功后可以缓存结果，避免频繁请求服务器
  • 错误处理：实现合理的重试机制和降级策略，确保网络异常时不影响用户体验
  • 安全性：不要在客户端代码中硬编码密钥，建议从配置文件或环境变量读取
  • 项目名称：确保项目名称与后台创建的项目名称完全一致（区分大小写）

密钥格式建议

  • 自动生成格式：KH-XXXXXXXX-XXXXXXXX - 适合软件授权
  • 手机号：13800138000 - 适合移动应用
  • 邮箱：user@example.com - 适合Web应用
  • 自定义字符串：任意格式 - 根据业务需求自定义