token de OIDC
Los agentes en la nube pueden emitir JWT de OIDC de corta duración desde la VM y usarlos para asumir roles en la nube o llamar a servicios internos sin almacenar credenciales de larga duración en Secretos.
Los agentes llaman a esta API con sus herramientas de terminal. No necesitas ejecutar estas solicitudes tú mismo.
Para que un agente emita tokens, incluye esto en tu instrucción:
Para emitir tokens de OIDC, sigue las instrucciones enhttps://cursor.com/docs/cloud-agent/identityEsta API es local a la VM del agente. No está relacionada con la API de agentes en la nube, que usa claves de API de Cursor y gestiona agentes desde fuera de la VM. El mismo socket también proporciona metadatos del agente para valores que no pertenecen a una credencial.
Las VM de agentes en la nube gestionadas por Cursor proporcionan el socket de tokens. Cada token que emiten incluye agent_runtime: managed.
Cómo funciona
- El agente llama al socket local y solicita un token con una audiencia que espera el verificador.
- Cursor firma un JWT RS256 vinculado a ese agente y propietario.
- El agente envía el JWT a tu nube o a un verificador (AWS STS, GCP, Azure, Vault o un servicio que ejecutes).
- El verificador comprueba la firma con las JWKS publicadas por Cursor y autoriza en función de afirmaciones como
sub,team_idocloud_agent_id.
Emite un token
El agente emite un token a través del socket Unix en CURSOR_AGENT_SOCKET. En las VM gestionadas por Cursor, el valor predeterminado es /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/oidcLas solicitudes se realizan mediante HTTP a través de un socket Unix. El nombre de host de la URL se ignora.
Incluye un nonce opcional si tu verificador espera vinculación de repetición:
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/oidcSolicitud
POST /v1/tokens/oidc a través del socket Unix. Se requiere Content-Type: application/json. El tamaño máximo del cuerpo es de 4 KB.
| Campo | Obligatorio | Descripción |
|---|---|---|
aud | Sí | Cadena de audiencia que comprueba el verificador. ASCII imprimible, sin espacios en blanco y con un máximo de 512 caracteres. Ejemplos: sts.amazonaws.com, https://oidc.example.com. |
nonce | No | Cadena opaca que se incluye en la afirmación nonce del JWT. Máximo 512 caracteres. |
sub_claim | No | Nombre de afirmación que se coloca en sub como <name>:<value>, para verificadores que solo comparan sub y aud. Máximo 64 caracteres. El descubrimiento enumera los nombres admitidos en x_cursor_sub_claims_supported; actualmente, team_id. Se rechazan los nombres no admitidos. Si la afirmación no tiene valor para este agente, como team_id en una cuenta personal, la emisión falla en lugar de recurrir al sujeto predeterminado. |
Cursor no usa una lista de permitidos para las audiencias. El verificador debe rechazar valores de aud inesperados.
Respuesta
{ "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...", "expires_at": 1785500000}| Campo | Descripción |
|---|---|
token | JWT firmado. |
expires_at | Vencimiento en segundos Unix. Coincide con la afirmación exp del JWT. |
Los tokens son válidos durante 5 minutos. No hay ningún endpoint de actualización. Emite uno nuevo cuando se necesite un token nuevo.
Cuándo aparecen las afirmaciones
Los scripts de instalación pueden emitir tokens a través del mismo socket. Un token solo incluye afirmaciones que existen en el momento de su emisión: turn_id y turn_start no están presentes hasta que comienza un turno de programación, y branch_name no está presente hasta que la ejecución registra una rama. Las afirmaciones de propietario, equipo y repositorio se establecen desde la creación del agente.
Si el socket no está disponible justo después del arranque, vuelve a intentar la conexión.
Verificar un token
Publique estas URL en su proveedor de identidad o servidor de recursos:
| Endpoint | URL |
|---|---|
| Emisor | https://api.cursor.com |
| descubrimiento | https://api.cursor.com/.well-known/openid-configuration |
| JWKS | https://api.cursor.com/keys |
curl -sS https://api.cursor.com/.well-known/openid-configurationcurl -sS https://api.cursor.com/keysEl descubrimiento sigue OpenID Connect Discovery 1.0. Los tokens se emiten en la VM del agente, por lo que el documento de descubrimiento no incluye authorization_endpoint ni token_endpoint.
Cursor aún ofrece un segundo documento de descubrimiento en
https://api2.cursor.sh/cloud-agent/identity. Los tokens emitidos ya no incluyen
ese emisor. Dirige los verificadores a https://api.cursor.com.
Comprueba, como mínimo:
- La firma con RS256 y el
kidde JWKS - Que
issseahttps://api.cursor.com - Que
audsea la audiencia que espera tu servicio nbf/expcon un pequeño margen de desfase horario (nbfes 5 segundos anterior aiat)subu otras afirmaciones de identidad que use tu política
El descubrimiento incluye x_cursor_audience_bound: true. Cada token se emite para el aud proporcionado por quien realiza la llamada. No aceptes un token emitido para otra audiencia. El descubrimiento también publica x_cursor_sub_claims_supported, los nombres de las afirmaciones que una solicitud de emisión puede proyectar en sub con sub_claim.
Afirmaciones JWT
Encabezado: alg=RS256, typ=JWT y kid.
| Afirmación | Siempre presente | Descripción |
|---|---|---|
iss | Sí | https://api.cursor.com |
sub | Sí | Sujeto estable del propietario: user:<id> o service_account:<id> de forma predeterminada, o <claim>:<value> (por ejemplo, team_id:123) cuando la solicitud de emisión estableció sub_claim. No es una dirección de correo electrónico. |
aud | Sí | Audiencia de la solicitud de emisión. |
iat | Sí | Fecha de emisión, en segundos Unix. |
nbf | Sí | No válido antes de (iat - 5). |
exp | Sí | Vencimiento (iat + 300). |
jti | Sí | ID único por emisión. |
cloud_agent_id | Sí | ID del agente en la nube (bcId). |
nonce | No | Solo está presente si se incluyó en la solicitud de emisión. |
agent_runtime | Sí | managed en las VM de agentes en la nube gestionados por Cursor. |
owner_email | Cuando se conoce | Dirección de correo electrónico del usuario en minúsculas. Use sub u owner_user_id para las listas de permitidos; la dirección de correo electrónico puede cambiar. |
owner_user_id | Cuando se conoce | ID de usuario de Cursor, como cadena decimal. |
owner_service_account_id | Cuando se conoce | ID de la cuenta de servicio cuando esta es propietaria del agente. |
team_id | Cuando se conoce | ID del equipo propietario, como cadena decimal. |
turn_id | Cuando hay un turno activo | ID de este turno de programación. Es diferente de cloud_agent_id, que es el ID del agente en la nube (bcId). |
turn_start | Cuando hay un turno activo | Inicio de la ejecución, en segundos Unix. |
repo_url | Cuando se conoce | Repositorio principal en formato host/path, como github.com/acme/widgets. El nombre de host está en minúsculas, sin esquema, credenciales, puerto, consulta ni sufijo .git. En un agente de varios repositorios, este es solo el repositorio principal. |
repo_urls | Cuando se conoce | Todos los repositorios del espacio de trabajo, en el mismo formato que repo_url. El repositorio principal aparece primero y el resto está ordenado. Solo está presente cuando se conoce el conjunto completo. Su ausencia significa que no se conoce el conjunto, no que solo haya un repositorio. |
repo_count | Cuando se conoce | Número de entradas en repo_urls. Está presente exactamente cuando lo está repo_urls. Úselo con repo_url cuando su verificador solo pueda coincidir con un único valor (repo_count == 1). |
branch_name | Cuando se conoce | Rama actual. |
environment_id | Cuando se conoce | ID del entorno de Cursor que usó esta ejecución. |
source | Cuando se conoce | Cómo se inició el agente, por ejemplo, WEBSITE, API, SLACK o AUTOMATIONS. |
automation_id | Para automatizaciones | ID de automatización cuando source es AUTOMATIONS. |
repo_url es el repositorio principal. Para restringir un agente a repositorios específicos, fije el conjunto completo con repo_urls.
Modelo de confianza
El token identifica la ejecución del agente en la nube, no un proceso específico dentro de la VM. Cualquier proceso que pueda acceder al socket puede emitir un token: el agente, el código que ejecuta y los hooks. Restrinja los permisos a los que concedería a esa ejecución en su conjunto.
No puede elegir para qué agente es el token. Cursor completa las afirmaciones con datos de esta ejecución, por lo que un proceso en la VM no puede emitir un token para otro agente.
Límites de uso y errores
Cada VM de agente puede emitir 30 tokens por minuto, en ráfagas de hasta 10. El socket también acepta como máximo 8 conexiones a la vez. Ese límite se comparte con los metadatos del agente. Almacene en caché un token hasta que caduque en lugar de emitir uno por llamada.
Reintenta 429, 503, 500, 502 y 504 con una espera progresiva. Considera 403 un error fatal: este agente no tiene permiso para emitir tokens.
Los cuerpos de error incluyen un código legible por máquina. Los errores de solicitud no válida (400, 404, 405, 413 y 415) también incluyen una cadena usage que reitera el contrato completo de la solicitud. Los errores de límite de uso y saturación solo incluyen el código:
{ "error": "invalid_aud", "usage": "POST /v1/tokens/oidc ..." }{ "error": "rate_limited" }| HTTP | error | Cuándo |
|---|---|---|
| 400 | invalid_json, invalid_aud, invalid_nonce o invalid_sub_claim | Cuerpo de la solicitud no válido |
| 404 | not_found | Ruta incorrecta |
| 405 | method_not_allowed | No es POST |
| 413 | body_too_large | Cuerpo de más de 4 KB |
| 415 | invalid_content_type | Falta Content-Type o no es JSON |
| 429 | rate_limited | Se superó el límite de emisión por agente; respete Retry-After |
| 503 | saturated | Demasiadas conexiones; respete Retry-After |
| 500 | host_error | Error interno; reintente |
| 502 / 504 | backend_unreachable | Cursor no pudo emitir el token; reintente |
| Otro | backend_error | Cursor rechazó la emisión. 400 significa que corrija la solicitud (por ejemplo, un sub_claim no compatible o sin valor para este agente). 403 es fatal. Se puede reintentar con 503. |
Ejemplo de AWS IAM
Usa OIDC si quieres que AWS confíe en JWT firmados por Cursor con AssumeRoleWithWebIdentity. Para el flujo más sencillo de asunción de roles gestionado por Cursor (ID externo + CURSOR_AWS_ASSUME_IAM_ROLE_ARN), consulta Uso de roles de AWS IAM.
- Crea un proveedor de identidad OIDC de IAM con la URL
https://api.cursor.com. - Establece la audiencia en
sts.amazonaws.com(u otra audiencia que requiera tu rol). - Configura la relación de confianza del rol solo para los sujetos y equipos que quieras autorizar.
Ejemplo de política de confianza:
{ "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:*" } } } ]}Restrinja esto con un sub exacto, como user:42 para un usuario o service_account:<id> para un agente que se ejecuta como una cuenta de servicio. Las políticas de confianza de AWS solo comprueban aud y sub, así que limite la confianza a un equipo emitiendo con "sub_claim":"team_id" y haciendo coincidir el sujeto proyectado:
"StringEquals": { "api.cursor.com:aud": "sts.amazonaws.com", "api.cursor.com:sub": "team_id:123"}Siga las instrucciones vigentes de AWS IAM OIDC para crear el proveedor y configurar las huellas digitales.
El agente emite un token con "aud":"sts.amazonaws.com" (más "sub_claim":"team_id" cuando su política de confianza coincida con el sujeto del equipo) y pase el JWT a STS. Si usa listas de permitidos de red, permita sts.amazonaws.com (y cualquier host regional de STS que use).
Otros verificadores
Los mismos tokens funcionan con cualquier verificador compatible con OIDC:
- GCP Workload Identity Federation
- Azure credenciales federadas / Entra ID
- Vault autenticación JWT/OIDC
- API internas que validan JWT con RS256
Configura el proveedor con la URL de descubrimiento, exige tu audiencia y autoriza según afirmaciones como sub, team_id o cloud_agent_id. Para restringir un agente a repositorios específicos, fija el conjunto completo con repo_urls; repo_url nombra solo el repositorio principal.
La emisión solo usa el socket local. El intercambio del JWT con AWS, GCP, Azure o tu servicio sigue requiriendo acceso de red saliente a esos hosts.
Páginas relacionadas
- Metadatos del agente para metadatos de ejecución de clave-valor en el mismo socket
- Secretos y red para consultar los secretos del panel de control y los controles de tráfico saliente
- Configuración del agente en la nube para la asunción de roles de AWS gestionados por Cursor
- Resumen de seguridad para consultar el modelo de aislamiento y acceso
- Cuentas de servicio cuando los agentes se ejecutan con una cuenta de servicio del equipo