《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以團隊服務賬戶運行時