跳到主要内容

API 认证

GeniSpace API 使用混合式 Bearer 认证方案，同时接受 JWT 访问令牌和 API 密钥（API Key）。所有 API 请求必须在请求头中携带有效的认证信息。

获取 API 密钥​

空间范围的 API 密钥在控制台中管理：

  1. 打开控制台，导航至 设置 → 集成
  2. 在 API 密钥区域，点击「创建 API 密钥」
  3. 妥善保管生成的密钥，密钥仅在创建时显示一次

API 密钥是 40 位字母数字令牌（无 sk- 前缀），例如 8OnG3iLUYdNq8PoO1JVW77aXbgHKBiOxIIufky7t。

使用方式​

在每个 API 请求的 HTTP 头部中添加 Authorization 字段：

Authorization: Bearer YOUR_API_KEY

推荐使用 Bearer 方案。对于 API 密钥，API 同样接受 ApiKey、API-Key 和 Token 前缀：

Authorization: ApiKey YOUR_API_KEY
Authorization: API-Key YOUR_API_KEY
Authorization: Token YOUR_API_KEY

请求示例​

curl -X GET https://api.genispace.cn/api/agents \
  -H "Authorization: Bearer 8OnG3iLUYdNq8PoO1JVW77aXbgHKBiOxIIufky7t" \
  -H "Content-Type: application/json"

校验 API 密钥​

要检查某个密钥是否有效，可调用校验端点（无需认证）：

curl -X POST https://api.genispace.cn/api/api-keys/validate \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "8OnG3iLUYdNq8PoO1JVW77aXbgHKBiOxIIufky7t" }'

响应使用统一信封格式，结果位于 data 中：

{
  "success": true,
  "message": "Operation successful",
  "data": {
    "valid": true
  }
}

POST /api/validate/api-key 提供了等价的端点。

安全建议​

  • 不要在客户端代码中硬编码 API 密钥
  • 使用环境变量存储密钥
  • 定期轮换密钥
  • 如果密钥泄露，请立即撤销（POST /api/api-keys/{id}/revoke）并创建新密钥

权限范围​

API 密钥的权限范围取决于创建者的空间角色和订阅计划。密钥可以访问其所绑定空间的资源。

相关文档​