《Cursor文档》-服务账户

服务账户适用于企业版方案。

服务账户是非个人用户账号，可帮助团队安全地大规模自动化基于 Cursor 的工作流。借助服务账户，您可以调用 API、认证命令行界面，以及调用云端代理，无需将集成与个别开发者的个人账户绑定。

为什么使用服务账户¶

随着团队不断探索通过 Cursor 云端代理、API 和命令行界面自动化编码任务的新方式，对集中、安全的自动化需求也愈发迫切。服务账户可满足以下需求：

与个人解耦：即使人员或角色发生变化，自动化仍可持续运行
安全管理凭据：轻松轮换 API 密钥，不中断工作流
集中式访问控制：管理员可在一处管理所有服务账户的权限
归因与可审计性：将云端代理运行关联到发起操作的服务或系统

主要功能¶

无需额外席位¶

企业版方案已包含服务账户，无需额外付费。它们不会占用席位许可证。

用量消耗¶

服务账户与人工用户一样，都会使用团队用量池中的用量。所有用量都会被记录，并显示在团队的使用分析和计费中。

云端代理集成¶

服务账户可以以编程方式启动云端代理运行。这支持以下自动化场景：

Linear 中创建工单后，触发云端代理实现功能
Sentry 中出现错误时，启动云端代理调查并修复问题
内部工程服务启动迁移或重构任务

管理员可见性¶

由服务账户发起的云端代理运行记录对所有团队管理员可见，便于在整个组织内查看和监督自动化工作流。

代码仓库访问¶

服务账户可以在通过 Cursor GitHub app 授权的任何代码仓库中发起云端代理运行。

服务账户需要团队级别的 GitHub 集成才能访问代码仓库。如果您只有个人 GitHub 集成，而没有团队级别的集成，服务账户将无法发起云端代理运行。

要在团队级别连接 GitHub：

前往 仪表盘 → 设置 → 集成
将 Cursor GitHub app 连接到您的组织
授权服务账户需要访问的代码仓库

代码仓库访问权限由为您团队的 GitHub app 安装配置的权限控制。

创建服务账户¶

管理员可以在 Cursor 仪表盘中创建和管理服务账户。

前往 仪表盘 → 设置 → API 密钥 → 服务账户
点击 新建服务账户
输入服务账户名称和可选描述
点击创建

创建服务账户时，系统会生成一个 API 密钥。请立即复制该密钥：它仅会显示一次，之后无法找回。

请妥善保管您的 API 密钥。如果丢失，需轮换密钥以生成新密钥。

管理 API 密钥¶

每个服务账户都可以关联多个 API 密钥。您可以：

查看已隐藏的密钥：查看每个密钥的末几位字符以便识别
轮换密钥：生成新密钥并使旧密钥失效
归档服务账户：归档服务账户并撤销其所有 API 密钥

轮换 API 密钥¶

要轮换 API 密钥：

前往 仪表盘 → 设置 → API 密钥 → 服务账户
找到该服务账户，点击其 API 密钥旁的轮换图标
立即复制新密钥

旧密钥将立即失效。请更新所有使用旧密钥的集成。

通过 API 使用服务账户¶

服务账户使用其 API 密钥进行认证。向 Cloud Agents API 发送请求时，请在 Authorization 请求头中使用该密钥：

curl -X POST https://api.cursor.com/agents \
  -H "Authorization: Bearer YOUR_SERVICE_ACCOUNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "owner/repo",
    "prompt": "Implement the feature described in issue #123"
  }'

完整的 API 参考请参阅 Cloud Agents API 文档。

通过命令行界面使用服务账户¶

服务账户可将 API 密钥设置为 CURSOR_API_KEY，以对 Cursor 命令行界面进行认证。这是在 CI/CD 流水线、cron 作业及其他无法通过浏览器登录的非交互式环境中运行命令行界面的推荐方式。

export CURSOR_API_KEY=your_service_account_api_key

# 在 CI 流水线中运行任务
agent -p --force "Refactor the authentication module to use OAuth 2.0"

该环境变量可在任何环境中使用，包括本地开发环境。有关所有身份验证选项，请参阅命令行界面身份验证文档；有关脚本编写模式，请参阅 Headless 命令行界面指南。

安全最佳实践¶

定期轮换密钥：为服务账户制定密钥轮换计划
使用描述性名称：根据用途为服务账户命名 (例如，“Linear Integration”“Sentry Auto-Fix”)
限制权限范围：为不同的自动化工作流创建独立的服务账户
监控用量：在团队的使用分析仪表盘中查看服务账户活动
撤销未使用的账户：归档不再使用的服务账户

归档服务账户¶

归档服务账户将：

撤销与该账户关联的所有 API 密钥
中断所有使用这些密钥的集成
保留账户记录以便审计

要归档服务账户：

前往 仪表盘 → 设置 → API 密钥 → 服务账户
点击服务账户旁的归档图标
确认归档操作

在服务账户页面点击 Show Archived 可查看已归档的账户。这有助于保留团队使用的服务账户的完整审计记录。

服务账户仅适用于企业版方案¶

借助用于 API 和云端代理的非个人用户账号，大规模自动化基于 Cursor 的工作流。