Cursor OIDC tokens: как настроить

Cursor OIDC tokens — это short-lived OIDC JWT, которые Cloud Agent минтит с локального Unix socket на своей VM и использует, чтобы принять облачную роль или вызвать внутренний сервис без long-lived credentials в Secrets. Канон: OIDC tokens. Это API локально на машине агента; оно не связано с Cloud Agents API и API keys.

Соседи: Cloud Agents, Secrets, Self-Hosted Workers, Cloud Agents API. Pillar: n8n / автоматизация.

Зачем OIDC вместо ключей в Secrets

Long-lived AWS_ACCESS_KEY_ID в Secrets tab удобен, но живёт месяцами и легко утекает в transcript/commit. OIDC даёт JWT на ~5 минут под конкретный aud. Managed VM ставят claim agent_runtime: managed; self-hosted с --identity-socket — agent_runtime: self_hosted.

Параметр	Значение по доке	Заметка
Socket	CURSOR_AGENT_SOCKET (managed: /run/cursor/api.sock)	HTTP поверх Unix socket; hostname в URL игнорируется
Endpoint	POST /v1/tokens/oidc	Content-Type: application/json; body ≤ 4 KB
Алгоритм	RS256 JWT	kid в header; проверка по JWKS
Issuer	https://api.cursor.com	Не старый api2.cursor.sh
TTL	~5 минут (exp = iat + 300)	Refresh нет — минтите снова
Обязательный aud	да, до 512 printable ASCII	Verifier обязан резать чужой aud

Сверка: cursor.com/docs/cloud-agent/identity (проверка 2026-09-19).

Mint с агента

В промпт агенту можно дать ссылку на док identity. Пример mint:

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

Ответ: token (JWT) и expires_at (Unix seconds). Опционально nonce для replay binding и sub_claim (team_id / organization_id / environment_id), если verifier матчит только sub+aud. Cursor не allowlist-ит audiences — это зона вашего verifier.

Verify: discovery и JWKS

• Discovery: https://api.cursor.com/.well-known/openid-configuration
• JWKS: https://api.cursor.com/keys
• Проверяйте: RS256 + kid, iss, aud, nbf/exp (nbf = iat − 5), нужные claims.
• x_cursor_audience_bound: true — не принимайте токен с чужим aud.

Старый discovery https://api2.cursor.sh/cloud-agent/identity ещё может отвечать, но minted tokens больше не несут тот issuer.

Claims, на которые опираться

Всегда есть: iss, sub (user:<id> или service_account:<id>, не email), aud, iat, nbf, exp, jti, cloud_agent_id (bcId), agent_runtime. Условно: team_id, repo_url/repo_urls, branch_name, environment_id, source (WEBSITE/API/SLACK/AUTOMATIONS), turn_id после старта coding turn. Для allowlist лучше sub / owner_user_id, не email.

Self-hosted

agent worker --pool gpu --identity-socket start
# My Machines без pool:
agent worker --identity-socket start

Флаг по умолчанию выключен. Worker открывает socket на claimed agent и выставляет CURSOR_AGENT_SOCKET. Контракт mint тот же; metadata API на self-hosted worker не отдаёт.

Trust model коротко

Токен идентифицирует Cloud Agent run, не один процесс. Агент, код, который он запустил, и hooks с доступом к socket могут минтить. Scope прав — как для всего run целиком.

Маршрут на один вечер

1. Выберите cloud role / Vault audience и настройте verifier на iss + JWKS api.cursor.com.
2. В промпте Cloud Agent укажите mint по identity docs с нужным aud.
3. Проверьте claims (cloud_agent_id, repo_url, team_id) в STS/IdP.
4. Уберите long-lived access keys из Secrets, если роль уже через OIDC.
5. Для своего флота включите --identity-socket на worker.

Типичные ошибки

• Путать OIDC socket API с Cloud Agents HTTP API (api.cursor.com/v1/agents + API key).
• Принимать токен с любым aud.
• Кешировать JWT дольше 5 минут без повторного mint.
• Строить allowlist на email вместо sub / owner_user_id.
• Забывать —identity-socket на self-hosted worker.

FAQ: Cursor OIDC tokens

Вывод

OIDC tokens — короткий JWT с socket агента под ваш aud. Issuer api.cursor.com, TTL ~5 минут, проверка через JWKS. Для управления агентами снаружи нужен отдельный Cloud Agents API; для кредов в env — Secrets tab.