Token 管理

API 访问令牌的管理指南

概述

Token 是调用 NDPR API 的凭证。每个 Token 可以关联到一个服务器，并具有相应的权限。

创建 Token

端点

Text
POST /token/get

请求参数

参数	类型	必填	说明
uuid	string	✅	服务器唯一标识符
mail	string	✅	管理员邮箱
key	string	✅	管理员密钥的 SHA256 哈希

示例

Bash
# 计算密钥哈希
KEY_HASH=$(echo -n "admin" | sha256sum | cut -d' ' -f1)

# 创建 Token
curl -X POST http://localhost:5030/token/get \
  -H "Content-Type: application/json" \
  -d "{
    \"uuid\": \"server-001\",
    \"mail\": \"admin@example.com\",
    \"key\": \"$KEY_HASH\"
  }"

响应

JSON
{
    "token": "aBcD1234EfGh5678IjKlMnOpQrSt"
}

删除 Token

端点

Text
POST /token/del

示例

Bash
curl -X POST http://localhost:5030/token/del \
  -H "Content-Type: application/json" \
  -d "{
    \"token\": \"aBcD1234EfGh5678IjKlMnOpQrSt\",
    \"key\": \"$KEY_HASH\"
  }"

查询 Token 列表

端点

Text
GET /token/list

查询参数

参数	类型	必填	说明
mail	string	✅	邮箱地址
key	string	✅	密钥哈希

示例

Bash
curl "http://localhost:5030/token/list?mail=admin@example.com&key=$KEY_HASH"

响应

JSON
{
    "tokens": [
        {
            "uuid": "server-001",
            "token": "aBcD1234EfGh5678IjKlMnOpQrSt"
        },
        {
            "uuid": "server-002",
            "token": "XyZw9876VuTs5432QrPoNmKlJi"
        }
    ]
}

验证 Token

端点

Text
POST /token/auth

示例

Bash
curl -X POST http://localhost:5030/token/auth \
  -H "Content-Type: application/json" \
  -d "{
    \"token\": \"aBcD1234EfGh5678IjKlMnOpQrSt\",
    \"key\": \"$KEY_HASH\"
  }"

响应

JSON
{
    "message": "Passed"
}

权限管理

授予上传权限

默认创建的 Token 没有上传封禁数据的权限，需要手动授权：

Text
POST /token/permission/add

Bash
curl -X POST http://localhost:5030/token/permission/add \
  -H "Content-Type: application/json" \
  -d "{
    \"token\": \"aBcD1234EfGh5678IjKlMnOpQrSt\",
    \"key\": \"$KEY_HASH\"
  }"

撤销上传权限

Text
POST /token/permission/del

检查权限

Text
POST /token/permission/auth

Bash
curl -X POST http://localhost:5030/token/permission/auth \
  -H "Content-Type: application/json" \
  -d "{
    \"token\": \"aBcD1234EfGh5678IjKlMnOpQrSt\",
    \"key\": \"$KEY_HASH\"
  }"

安全建议

1. 每个服务器使用独立的 Token<br>

2. 定期轮换 Token<br>

3. 妥善保存 Token，不要提交到公开仓库<br>

4. 及时撤销不再使用的 Token

</div>

错误响应

状态码	错误消息	说明
400	Missing params	缺少必要参数
400	UUID not found	UUID 不存在
400	Token not found	Token 不存在
401	Auth failed	认证失败
500	Server error	服务器错误