Provisioning API（高级功能）

Provisioning API 用于受控后端自动创建、修改、撤销和轮换 Lumoswitch Access Key。它不适合浏览器、桌面客户端或普通用户脚本。

仅实例管理员或获得明确授权的自动化系统应使用此 API。

前提与鉴权

服务方必须先为实例启用 Provisioning Token。每个请求使用：

Authorization: Bearer YOUR_PROVISIONING_TOKEN
Content-Type: application/json

Provisioning Token 权限高于普通 Access Key。不要将它下发给调用模型的客户端，也不要与 Lumoswitch Access Key 混用。

以下示例使用控制 API 地址：

export LUMOSWITCH_CONTROL_URL="https://your-control.example.com"
export LUMOSWITCH_PROVISIONING_TOKEN="your-provisioning-token"

创建 Access Key

curl "$LUMOSWITCH_CONTROL_URL/provisioning/access-keys" \
  -H "Authorization: Bearer $LUMOSWITCH_PROVISIONING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "target-user-id",
    "name": "production-agent",
    "projectId": "optional-project-id",
    "rateLimitRequestsPerMinute": 60,
    "allowedModels": ["assistant-prod"]
  }'

完整 Key 只会在创建响应中返回一次，应立即写入目标密钥管理系统。

修改 Access Key

curl -X PATCH "$LUMOSWITCH_CONTROL_URL/provisioning/access-keys/KEY_ID" \
  -H "Authorization: Bearer $LUMOSWITCH_PROVISIONING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "target-user-id",
    "isEnabled": true,
    "rateLimitRequestsPerMinute": 30,
    "allowedModels": ["assistant-prod"]
  }'

撤销 Access Key

curl -X DELETE "$LUMOSWITCH_CONTROL_URL/provisioning/access-keys/KEY_ID" \
  -H "Authorization: Bearer $LUMOSWITCH_PROVISIONING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId":"target-user-id"}'

撤销后，使用旧 Key 的客户端会立即失去访问能力。

轮换 Access Key

curl -X POST "$LUMOSWITCH_CONTROL_URL/provisioning/access-keys/KEY_ID/rotate" \
  -H "Authorization: Bearer $LUMOSWITCH_PROVISIONING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "target-user-id",
    "name": "production-agent-rotated",
    "allowedModels": ["assistant-prod"]
  }'

当前轮换操作会撤销旧 Key 并创建新 Key。调用方必须可靠保存响应中的新值，并准备处理客户端切换窗口。

安全建议

只在受控后端保存 Provisioning Token。
为自动化任务限制网络访问和操作范围。
不把 Token 写入 CI 输出、错误消息或仓库变量示例。
自动化应记录目标 userId、Key ID 和操作结果，但不得记录完整 Key。

API 参考 Metrics 监控（高级）