Actuar en nombre de usuarios

Las aplicaciones de Origin usan tokens de usuario de la instalación para actuar en nombre de los miembros del espacio de nombres en el que están instaladas. Cada solicitud se limita a los permisos que tienen tanto la instalación como el usuario.

Usa la URL base de la API de Origin y el modelo de errores. Emite los tokens con un JWT de aplicación.

Cómo funciona

1. Un administrador del espacio de trabajo aprueba el scope namespace:user_tokens:write para la instalación de tu aplicación.
2. Opcionalmente, confirma la identidad de Cherri Code del usuario. Origin devuelve un comprobante firmado con su ID user_….
3. Firma un JWT de aplicación y emite un token de usuario de la instalación para el ID o el correo electrónico del usuario.
4. Usa el token de usuario de la instalación con la API REST o con Git por HTTPS hasta expiresAt y, después, emite otro.

Solicitar el scope

Añade namespace:user_tokens:write al parámetro scope de la URL de instalación. Si se trata de una instalación existente, envía también include_granted_scopes=true para que el administrador solo tenga que aprobar el nuevo scope.

/codebase/apps/install  ?client_id=APP_ID  &scope=namespace:user_tokens:write%20repository:pull_requests:write  &redirect_uri=REGISTERED_CALLBACK  &state=RANDOM_ANTI_FORGERY_VALUE  &include_granted_scopes=true

Este scope permite que la instalación emita tokens para cualquier miembro activo de su espacio de nombres. No puede incluirse en los scopes de un token. Los demás scopes aprobados por el administrador siguen limitando los permisos de cada token.

Cuándo confirmar a un usuario

La confirmación de un usuario es opcional: la aprobación del administrador para namespace:user_tokens:write incluye a todos los miembros del espacio de nombres.

Confirma a un usuario para vincular su cuenta en tu producto con su cuenta de Cherri Code, o para verificar su identidad en vez de confiar en una dirección de correo electrónico proporcionada por el usuario. El comprobante acredita que, en el momento de la confirmación, el usuario había iniciado sesión, tenía el ID user_… y el correo electrónico indicados, y pertenecía al espacio de nombres.

Los comprobantes acreditan la identidad, pero no otorgan permisos. Create Installation User Token no acepta ni requiere ningún comprobante.

Confirmación del usuario

Redirige al usuario a Origin

Abre esta URL en el navegador del usuario:

/codebase/apps/user-confirmation  ?installation_id=INSTALLATION_ID  &redirect_uri=REGISTERED_CALLBACK  &state=RANDOM_ANTI_FORGERY_VALUE

Envía cada parámetro una sola vez como máximo. Tras el inicio de sesión, se muestra un error si falta algún parámetro obligatorio o se repite alguno.

Qué ve el usuario

Los usuarios que no hayan iniciado sesión deben iniciarla en Cherri Code y después volver al mismo enlace con sus parámetros. Origin valida los parámetros tras el inicio de sesión, por lo que incluso los enlaces incorrectos requieren iniciar sesión antes de mostrar un error.

Origin muestra el nombre, el icono y la descripción de tu aplicación junto con el espacio de nombres de la instalación. También indica qué datos recibirá tu aplicación:

• ID de usuario de Cherri Code (user_…)
• Correo electrónico
• Slug e ID del espacio de nombres de Origin

La página explica que, al confirmar, se comparten la identidad y la membresía actual del espacio de nombres, sin conceder acceso al repositorio. El usuario elige Confirmar o Cancelar.

Solo pueden confirmar los miembros activos del equipo propietario o el propietario de un espacio de nombres personal.

Callback

Cuando el usuario confirma, Origin redirige a tu callback:

https://app.example.com/origin/confirm?confirmation_receipt=RECEIPT_JWT&state=RANDOM_ANTI_FORGERY_VALUE

Verifica el recibo de confirmación antes de leer las afirmaciones sobre el usuario que contiene. El callback incluye state solo si la URL de confirmación incluía un valor no vacío. Confía en la afirmación state firmada, no en el parámetro de la consulta.

Si el usuario cancela o no puede confirmar, no se envía ningún callback ni se produce ninguna redirección. Interpreta la ausencia de callback como "no confirmado" y deja que el usuario empiece de nuevo.

Recibo de confirmación

confirmation_receipt es un JWT compacto firmado por Origin con las mismas claves que los comprobantes de instalación.

Encabezado JOSE:

{  "alg": "EdDSA",  "kid": "origin-key-id",  "typ": "origin-user-confirmation-receipt+jwt"}

Afirmaciones:

{  "iss": "https://api.cursor.com/v1/origin",  "aud": "app_01...",  "sub": "user_01...",  "installation_id": "i_01...",  "namespace_id": "ns_01...",  "email": "[email protected]",  "iat": 1786465200,  "exp": 1786465500,  "jti": "RECEIPT_UUID",  "state": "ORIGINAL_VALUE"}

• aud es el ID de tu aplicación; sub es el ID user_… del usuario que confirmó, que se usa como userId al emitir el token.
• installation_id y namespace_id identifican la instalación y el espacio de nombres en los que se confirmó la membresía.
• email es el correo electrónico de la cuenta del usuario en el momento de la confirmación.
• Los recibos caducan cinco minutos después de su emisión. jti es único para cada recibo.
• state solo se incluye si la URL de confirmación contenía un valor no vacío.

Verifica el recibo antes de confiar en el callback:

1. Obtén la clave de firma del JWKS a partir del encabezado kid.
2. Exige alg: EdDSA y typ: origin-user-confirmation-receipt+jwt para distinguir los recibos de confirmación de los comprobantes de instalación y los tokens de acceso.
3. Valida la firma, iss, aud y exp.
4. Comprueba que installation_id y el state firmado coincidan con los valores que enviaste.

Rechaza el callback si falla alguna comprobación.

Errores de confirmación

Ante cualquier fallo, el usuario permanece en la página de Cherri Code y no se llama a tu callback.

Emitir un token de usuario de la instalación

Llama a Crear un token de usuario de la instalación, POST /v1/origin/app/installations/{installationId}/user_access_tokens, con un JWT de aplicación. Establece uno solo de estos campos: userId o userEmail.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/app/installations/INSTALLATION_ID/user_access_tokens' \  --header 'Authorization: Bearer APP_JWT' \  --header 'Content-Type: application/json' \  --data '{  "userId": "user_01...",  "scopes": [    "repository:pull_requests:write"  ],  "repositoryIds": [    "repo_01..."  ]}'

{  "token": "YOUR_INSTALLATION_USER_TOKEN",  "expiresAt": "2026-01-01T00:15:00Z"}

El usuario debe tener una cuenta de Cherri Code activa y cumplir las reglas de membresía del espacio de nombres. Los usuarios desconocidos, quienes no son miembros y los correos electrónicos que coinciden con varios miembros devuelven el mismo 403.

Si se establecen tanto scopes como repositoryIds, la emisión solo se realiza correctamente si tanto la instalación como el usuario tienen todos los scopes solicitados en todos los repositorios indicados. Con menos límites, los permisos se comprueban en cada solicitud.

Duración

expiresAt es, como máximo, 15 minutos posterior a la emisión y nunca posterior al exp del JWT de aplicación, como ocurre con los tokens de acceso de instalación. No hay token de actualización: emite otro con un JWT de aplicación recién generado cuando caduque. Cada emisión consume 1 punto del límite de uso del JWT de aplicación.

Usar el token

Trata los tokens de usuario de la instalación como opacos: no inspecciones ni analices su contenido. Envía el token como credencial Bearer a la API REST o como contraseña para Git por HTTPS con el nombre de usuario x-access-token:

Authorization: Bearer YOUR_INSTALLATION_USER_TOKEN

Cada solicitud debe ajustarse a los scopes aprobados y la selección de repositorios de la instalación, los grants de Origin del usuario y los límites del token. De lo contrario, devuelve 403, o 404 si el recurso no es visible.

Los campos de actor identifican al usuario y pueden incluir performedVia.app con el id de tu aplicación y un displayName opcional. La atribución se aplica a la acción que describe ese campo: en el autor de un comentario, identifica la aplicación que creó el comentario, no una aplicación que lo haya editado o eliminado después. performedVia no aparece en las acciones realizadas directamente por el usuario y puede no aparecer cuando los datos de delegación no están disponibles.

Errores de emisión

Revocación

No se pueden revocar tokens individuales. Estos cambios afectan al acceso mediante tokens:

• Desinstalar o eliminar la aplicación invalida sus tokens de usuario antes de expiresAt. Las solicitudes devuelven 401.
• Cerrar la cuenta de Cherri Code del usuario invalida sus tokens. Las solicitudes devuelven 401.
• Quitar namespace:user_tokens:write o suspender la instalación impide emitir nuevos tokens. Los tokens emitidos caducan en expiresAt.
• Los cambios en los grant de la instalación o del usuario se aplican, a más tardar, en expiresAt.

Notas de seguridad

• Emite los tokens solo cuando se necesiten y con los scopes y repositoryIds mínimos necesarios. Trátalos como contraseñas: no los almacenes ni los registres.
• Identifica las cuentas vinculadas por sub, no por email: el ID user_… del usuario no cambia, pero su correo electrónico sí puede cambiar.
• Verifica las direcciones de correo electrónico antes de emitir tokens con userEmail. Una dirección introducida manualmente puede corresponder a otro miembro.
• Usa cada comprobante una sola vez. Registra su jti y rechaza cualquier intento de reutilizarlo durante sus cinco minutos de validez.
• Un comprobante no es una credencial: no lo envíes como token Bearer ni lo registres, ya que contiene el correo electrónico del usuario.
• Los comprobantes reflejan la membresía en el momento de la confirmación. Cada vez que se emite un token, se vuelve a comprobar la membresía. Por eso, un comprobante almacenado no permite emitir tokens para alguien que ya no es miembro.