《Cursor文档》-OIDC 身份令牌

云端代理可在 VM 内签发短期有效的 OIDC JWT，并使用这些 OIDC 身份令牌承担云角色或调用内部服务，无需在 机密信息 中存储长期凭据。

智能体通过其终端工具调用此 API。您无需自行发起这些请求。

要让智能体签发 token，请在提示词中加入以下内容：

要签发 OIDC 身份令牌，请按照以下地址中的说明操作
https://cursor.com/docs/cloud-agent/identity

此 API 位于智能体 VM 本地。它与 云端代理 API 无关；后者使用 Cursor API 密钥，并从 VM 外部管理 agents。同一套接字还提供智能体元数据，用于存放不应包含在凭据中的值。

Cursor 管理的云端代理 VM 提供 token 套接字。其签发的每个 token 都带有 agent_runtime: managed。

工作原理¶

1. 智能体调用本地套接字，请求获取验证方预期受众的 token。
2. Cursor 签发与该智能体和所有者绑定的 RS256 JWT。
3. 智能体将 JWT 发送到你的云服务或验证方 (AWS STS、GCP、Azure、Vault 或你运行的服务) 。
4. 验证方根据 Cursor 发布的 JWKS 验证签名，并基于 sub、team_id 或 cloud_agent_id 等声明进行授权。

签发 token¶

智能体通过 CURSOR_AGENT_SOCKET 指定的 Unix 套接字签发 token。在 Cursor 管理的 VM 上，默认值为 /run/cursor/api.sock。

curl --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \
  -H 'Content-Type: application/json' \
  -d '{"aud":"sts.amazonaws.com"}' \
  http://cursor-agent/v1/tokens/oidc

请求通过 Unix 套接字使用 HTTP。URL 中的主机名会被忽略。

当验证方要求进行重放绑定时，可包含可选的 nonce：

curl --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \
  -H 'Content-Type: application/json' \
  -d '{"aud":"https://oidc.example.com","nonce":"unpredictable-value"}' \
  http://cursor-agent/v1/tokens/oidc

请求¶

通过 Unix 套接字发送 POST /v1/tokens/oidc 请求。必须使用 Content-Type: application/json。最大请求体大小为 4 KB。

Cursor 不会将受众列入允许列表。验证方必须拒绝未预期的 aud 值。

响应¶

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...",
  "expires_at": 1785500000
}

token 的有效期为 5 分钟。不提供刷新端点。需要新 token 时，请重新签发。

声明何时出现¶

安装脚本可通过同一套接字签发 token。token 仅包含签发时有值的声明：在编码轮次开始前，turn_id 和 turn_start 不存在；在运行记录分支前，branch_name 不存在。所有者、团队和代码仓库声明从创建智能体时起即已设置。

如果启动后套接字暂时不存在，请重试连接。

验证令牌¶

将以下 URL 提供给您的身份提供商或资源服务器：

curl -sS https://api.cursor.com/.well-known/openid-configuration
curl -sS https://api.cursor.com/keys

发现机制遵循 OpenID Connect Discovery 1.0。token 在智能体 VM 上签发，因此发现文档不包含 authorization_endpoint 或 token_endpoint。

较早的颁发方 URL¶

Cursor 仍在
https://api2.cursor.sh/cloud-agent/identity 提供第二份发现文档。新签发的 token 不再携带
该颁发方。请将验证方指向 https://api.cursor.com。

至少检查以下内容：

• 使用 RS256 和 JWKS kid 验证签名
• iss 是否为 https://api.cursor.com
• aud 是否为你的服务预期的受众
• nbf / exp 是否留有少量时钟偏差余量 (nbf 比 iat 早 5 秒)
• 你的策略使用的 sub 或其他声明

发现文档包含 x_cursor_audience_bound: true。每个 token 都会针对调用方提供的 aud 签发。请勿接受为其他受众签发的 token。发现文档还发布了 x_cursor_sub_claims_supported，其中列出了签发请求可通过 sub_claim 投射到 sub 的声明名称。

JWT 声明¶

请求头：alg=RS256、typ=JWT 和 kid。

repo_url 是主代码仓库。要将智能体限制在特定代码仓库中，请使用 repo_urls 固定完整集合。

信任模型¶

该 token 标识的是云端代理运行，而非 VM 内的某个特定进程。任何能访问套接字的进程都可以签发 token，包括智能体、它运行的代码和钩子。应仅授予相当于对该次运行整体授予的权限。

你无法选择 token 对应哪个智能体。Cursor 会根据此次运行填充声明，因此 VM 中的进程无法为其他智能体签发 token。

速率限制和错误¶

每个智能体 VM 每分钟最多可签发 30 个 token，单次突发最多 10 个。套接字同时最多接受 8 个连接。该上限与智能体元数据共享。请将 token 缓存至其过期，而非每次调用都签发。

对 429、503、500、502 和 504 采用退避策略重试。403 属于致命错误：该智能体无权签发 token。

错误响应体包含机器可读的代码。无效请求错误 (400、404、405、413 和 415) 还包含一个 usage string，用于重述完整的请求约定。速率限制和饱和错误则仅包含代码：

{ "error": "invalid_aud", "usage": "POST /v1/tokens/oidc ..." }

{ "error": "rate_limited" }

AWS IAM 示例¶

如果希望 AWS 通过 AssumeRoleWithWebIdentity 信任由 Cursor 签名的 JWT，请使用 OIDC。若要使用更简单的 Cursor 管理的 assume-role 流程 (External ID + CURSOR_AWS_ASSUME_IAM_ROLE_ARN) ，请参阅使用 AWS IAM 角色。

1. 创建一个 IAM OIDC 身份提供商，URL 设为 https://api.cursor.com。
2. 将受众设置为 sts.amazonaws.com (或角色所需的其他受众) 。
3. 仅允许您指定的主体和团队信任该角色。

信任策略示例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/api.cursor.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "api.cursor.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "api.cursor.com:sub": "user:*"
        }
      }
    }
  ]
}

使用精确的 sub (如单个用户使用 user:42，或以服务账户身份运行的智能体使用 service_account:<id>) 进一步收紧此策略。AWS 信任策略仅匹配 aud 和 sub，因此可通过使用 "sub_claim":"team_id" 签发 token并匹配映射后的主体，将信任范围限定到某个团队：

"StringEquals": {
  "api.cursor.com:aud": "sts.amazonaws.com",
  "api.cursor.com:sub": "team_id:123"
}

请遵循最新的 AWS IAM OIDC 指引创建提供商并配置指纹。

智能体使用 "aud":"sts.amazonaws.com" 签发 token (当信任策略与团队主体匹配时，另加 "sub_claim":"team_id") ，并将 JWT 传给 STS。如果使用网络允许列表，请允许访问 sts.amazonaws.com (以及调用的任何区域性 STS 主机) 。

其他验证方¶

同一 token 可用于任何兼容 OIDC 的验证方：

• GCP Workload Identity Federation
• Azure 联合凭据 / Entra ID
• Vault JWT/OIDC 认证
• 验证 RS256 JWT 的内部 API

将 provider 配置为使用发现 URL，要求受众与你的值匹配，并基于 sub、team_id 或 cloud_agent_id 等声明进行授权。要将智能体限制在特定仓库中，请使用 repo_urls 固定完整集合；repo_url 仅指定主仓库。

签发仅使用本地套接字。与 AWS、GCP、Azure 或你的服务交换 JWT 时，仍需访问这些 host 的出站网络。

相关页面¶

• 智能体元数据：了解同一套接字上的键值对运行元数据
• 机密信息与网络：仪表盘机密信息和出站控制
• 云端代理设置：使用 Cursor 管理的 AWS 角色承担
• 安全概览：隔离和访问模型
• 服务账户：agents以团队服务账户运行时