cursor-api动态密钥(build-key)使用教程:如何生成sk-前缀Key并安全分享给团队
cursor-api动态密钥(build-key)使用教程:如何生成sk-前缀Key并安全分享给团队
cursor-api 是一个将 Cursor 账号能力转换为 OpenAI 兼容接口的 Rust 代理服务,其 /build-key 动态密钥接口可以把 Token 封装成 sk- 前缀的 API Key,方便团队成员像使用 OpenAI 官方 Key 一样调用对话接口。本教程带你从零完成生成、使用到安全分享的全流程。
一、什么是 cursor-api 的 build-key 动态密钥?
build-key 是 cursor-api 提供的密钥构建接口(POST /build-key),它把账号 Token 和一组动态配置(时区、代理、额度检查等)编码进一个 Key 里,格式为:
sk-{base64编码的配置数据}
成功调用后,接口一次返回 3 个等价 Key(见 build_key.rs 中的 BuildKeyResponse):
| 序号 | 形式 | 说明 |
|---|---|---|
| 1 | sk- 前缀完整 Key |
主 Key,包含动态配置,推荐分享 |
| 2 | 数字 Key 的 base64 版本 | 动态密钥别名 |
| 3 | 数字 Key 明文版本 | 128 位 + 64 位无符号整数组成,比常规 UUID 更难猜测 |
三者可互相替代认证,核心逻辑在 token.rs。相比旧版直接传 token 与 checksum 的方式(0.3 起已不再适用),动态密钥把配置内置进 Key,客户端只需用 Bearer sk-xxx 即可。
二、前置准备:获取 Token 并启动服务
1. 获取 Cursor Token
- 方式 A:浏览器访问 Cursor 官网并登录后,按 F12 打开开发者工具,在 Application → Cookies 中复制
WorkosCursorSessionToken的第三个字段; - 方式 B:运行仓库自带的 get-token 工具,自动从 Cursor 编辑器本地数据库读取令牌。
2. 启动 cursor-api
通过环境变量注入认证令牌后启动即可:
export AUTH_TOKEN="你的管理员令牌"
export PORT=3000
# 可选:自定义 Key 前缀,默认 sk-
export KEY_PREFIX="sk-"
KEY_PREFIX 的默认值定义在 lazy.rs。
三、生成 sk- 前缀 Key:POST /build-key 完整步骤
向 http://你的服务器:3000/build-key 发送 POST 请求,请求头带上管理员认证,请求体最简示例:
{
"token": "eyJ...(你的 JWT 令牌)",
"checksum": { "first": "64位Hex", "second": "64位Hex" },
"client_key": "64位Hex",
"config_version": "UUID,可选",
"session_id": "UUID",
"timezone": "Asia/Shanghai(可选)",
"disable_vision": false
}
可选参数还能控制 proxy_name(代理)、gcpp_host(代码补全区域)、enable_slow_pool、include_web_references、usage_check_models(额度检查模型范围)等,完整字段见 build_key.rs。
成功时返回:
{
"keys": ["sk-eyJhbGc...", "数字key的base64", "数字key明文"]
}
💡 拿到第 1 个
sk-Key 后,就可以把它分发给团队了。
四、使用 sk- Key 调用对话接口
拿到动态密钥后,任何支持 OpenAI 兼容协议的客户端都可以直接接入:
curl http://你的服务器:3000/v1/chat/completions \
-H "Authorization: Bearer sk-eyJhbGc..." \
-H "Content-Type: application/json" \
-d '{"model":"你的模型","messages":[{"role":"user","content":"你好"}]}'
- 对话接口:
POST /v1/chat/completions(支持流式与非流式) - 模型列表:
GET /v1/models - Key 前缀由服务端
KEY_PREFIX统一控制,校验逻辑见 config.rs
五、安全分享建议:把风险降到最低 🔒
1. 只分享 sk- Key,不要分享原始 Token
Token 是账号"根凭证",泄漏即等于交出账号;而动态密钥是派生凭证,服务端可通过 HMAC 校验其合法性(实现见 dynamic_key.rs)。
2. 用 share_token 降低管理员权限暴露
在 config.example.toml 中为团队配置 share_token,它仅有 Chat 端点权限,适合用于接口认证,避免把完整的 AUTH_TOKEN 暴露给团队。
3. 配置 dynamic_key_secret 加固密钥生成
dynamic_key_secret 用于验证动态密钥配置请求的来源合法性(防止恶意添加/修改),支持 hex: 原始密钥模式或 SHA256 密码哈希模式,可用 openssl rand -hex 64 生成;留空则自动禁用动态密钥功能。
4. 定期轮换与隔离
- 成员离职或怀疑泄漏时,重新调用
/build-key生成新 Key 即可; - 不同项目/成员可生成不同 Key,便于通过 logs 接口按 Key 追溯用量;
- 服务端务必监听内网地址或加反向代理鉴权,避免
/build-key暴露在公网。
六、常见问题 FAQ
Q1:动态密钥和直接传 Token 有什么区别?
动态密钥把 Token 和配置打包加密进 sk- Key,0.3 版本起直接传 token + checksum 的方式已不再适用。
Q2:数字 Key(后两个)什么时候用?
它们是 sk- Key 的缓存别名,长度更短,适合写入对 Key 长度敏感的配置项。
Q3:Key 会过期吗?
sk- Key 本身长期有效,但它绑定的 Cursor Token 有会话时效;Token 过期后需重新获取并重新 /build-key。
Q4:能否自定义 sk- 前缀?
可以,通过环境变量 KEY_PREFIX 修改,默认为 sk-。
七、相关资源速查
- 接口与字段定义:src/app/model/build_key.rs
- 接口处理实现:src/core/route/token.rs
- 密钥安全校验:src/app/model/dynamic_key.rs
- 服务端配置示例:config.example.toml
- 构建 Key 页面:static/build_key.html
掌握 /build-key 动态密钥后,你就能像管理 OpenAI 官方 Key 一样管理 cursor-api 的访问权限——生成快、分发安全、可追溯,是团队共用 AI 编程能力的推荐姿势。