foren.dev

API Token（管理类 API 凭证）

API Token 是给管理员或系统集成商调管理类 API 的凭证。

它和授权令牌不一样

凭证类型谁持有调哪些 API
---------
授权令牌客户 / 取证软件/authorize/token/ 等用户向端点
API Token (本页)管理员 / 系统集成商/plans/、/stats/、/webhooks/、/certs/generate/、/renew/、/upgrade/ 等

颁发流程

管理员                            集成商
    │                                │
    │   (后台) 生成                   │
    │   ┌─────────────────┐          │
    │   │ 名称、作用域     │          │
    │   │ 选 license 用户  │          │
    │   └────────┬────────┘          │
    │            ▼                    │
    │   生成明文 token                 │
    │   (仅显示一次)                  │
    │            │                    │
    │            │ (安全通道下发)    │
    │            └───────────────────▶│
    │                                 │
    │                            保存到 KMS
    │                            配置到 SDK

怎么生成

仅管理员可以生成：登录后台 → 侧边栏 API Tokens → + Generate Token：

  • Name（必填）：描述用途，例如 "Production CoForen Stats"
  • Scope：固定为 license
  • Expires At（可选）：留空 = 不过期

生成后明文 token 仅显示一次，请立即保存。

怎么调用 API

任何需要鉴权的端点都接受 Bearer token：

curl https://foren.dev/license/api/coforen/stats/ \
  -H "Authorization: Bearer f7c4...your-token-here...e2d1"

如果 token 无效：

{"ok": false, "error_code": "unauthorized", "message": "Invalid or expired API token"}

HTTP 状态码：401 Unauthorized。

速率限制

默认所有 API 端点：

端点组限流
------
激活 / 离线校验30 / 分钟 / IP
统计30 / 分钟 / IP
其他60 / 分钟 / IP

超出后返回 429 Too Many Requests。

撤销

在后台 API Tokens 列表中点击 Revoke。撤销后 token 立即不可用，但保留在列表中以便审计。

🔒 管理员限定内容
**示例 token 值（演示用）**：f7c4a1b9d8e2c5f3a6b8d4e1c5f3a6b8d4e1c5f...
请 登录管理员 后查看完整内容

重新生成

如果 token 泄露或怀疑泄露：

  1. 后台 → API Tokens → 找到对应 token → Regenerate
  2. 复制新的明文 token
  3. 下发到客户端并替换旧的
  4. 验证集成使用新 token 正常工作

旧的 token 在 regenerate 瞬间失效。

安全建议

✅ 应该❌ 不应该
------
每个集成用独立 token共用同一个 token 给多个系统
存到 KMS / Vault写到 .env 提交到 git
设置明确过期时间（生产推荐 90 天）永不过期 token 给多个环境
监控 last_used_at假设 token 永远不被泄露

审计

每次 token 使用：

  • last_used_at 自动更新（可观察 token 是否仍在使用）
  • 可在后台查看最后使用时间

定期审计 last_used_at：

SELECT name, scope, last_used_at, expires_at
FROM api_tokens
WHERE is_active = 1
  AND (last_used_at IS NULL OR last_used_at < NOW() - INTERVAL 30 DAY);

下一步