OIDC 身份令牌

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

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

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

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

此 API 仅供运行智能体的机器本地使用。它与 云端代理 API 无关；后者使用 Cherri Code API 密钥，并从该机器外部管理 agents。在 Cherri Code 托管 VM 上，此套接字还会提供智能体元数据。

Cherri Code 托管的云端代理 VM 提供 token 套接字。它们签发的每个 token 都带有 agent_runtime: managed。自托管机器 worker 则在您使用 --identity-socket 启动它们时提供该套接字。其 token 带有 agent_runtime: self_hosted。请参阅自托管 workers。

工作原理

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

签发 token

智能体通过 CURSOR_AGENT_SOCKET 中路径所指的 Unix 套接字签发 token (在 Cherri Code 托管 VM 上，该值始终设置为 /run/cursor/api.sock；在自托管 workers 上，该路径会因已认领的智能体而异) 。

curl --unix-socket "${CURSOR_AGENT_SOCKET}" \  -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}" \  -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。

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

响应

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

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

声明何时出现

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

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

自托管 workers

使用 --identity-socket 启动自托管机器 worker 时，它会提供相同的 API：

agent worker --pool gpu --identity-socket start

该 flag 默认关闭。请在 worker command 中、start 之前传入。pool workers 和 我的机器 workers 使用相同的 flag。在我的机器 worker 上省略 --pool：

agent worker --identity-socket start

设置该 flag 后，worker 会为每个已声明的智能体打开一个套接字，并在该智能体的 shell 中将 CURSOR_AGENT_SOCKET 设为该套接字的 path。请求与响应合约、错误码以及速率限制均与 Cherri Code-managed VM 一致。

这些 token 会携带 agent_runtime: self_hosted，以及相同的所有者、团队和代码仓库声明。worker 提供 token API，但不提供智能体元数据。任何以 worker 的操作系统 user 身份运行的 process，都可以在该声明的套接字上签发 token。参见信任模型。

验证令牌

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

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

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

至少检查以下内容：

• 使用 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 标识的是云端代理运行，而非机器上的某个特定进程。任何能访问套接字的进程都可以签发 token，包括智能体、它运行的代码和钩子。应仅授予相当于对该次运行整体授予的权限。

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

在自托管 workers 上，智能体与 worker 进程以同一个操作系统用户身份运行。任何以该用户身份运行的进程都可以为已认领的运行签发 token。应将角色的作用域限定为你愿意在该机器上授予该用户的权限。

速率限制和错误

每个已认领的智能体每分钟最多可签发 30 个 token，单次突发最多 10 个。套接字同时最多接受 8 个连接。在 Cherri Code 托管 VM 上，这 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 信任由 Cherri Code 签名的 JWT，请使用 OIDC。若要使用更简单的 Cherri Code 管理的 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"}

信任策略在 Cherri Code 管理的 token 和自托管的 token 上看到的 aud 和 sub 是相同的。您无法把 agent_runtime 放进 sub。

请遵循最新的 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 的出站网络。

相关页面

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