Generación de un token de acceso de usuario para una aplicación de GitHub

Acerca de los tokens de acceso de usuario

Nota: Los tokens de acceso de usuario que expiran actualmente son una característica opcional y están sujetos a cambios. Para participar o no en la característica de expiración de tokens consulta "Activating optional features for GitHub Apps". Para obtener más información, consulta Tokens de acceso con caducidad de usuario a servidor para las GitHub Apps.

Un token de acceso de usuario es un tipo de token de OAuth. A diferencia de un token de OAuth tradicional, el token de acceso de usuario no usa ámbitos. En su lugar, usa permisos específicos. Un token de acceso de usuario solo tiene los permisos que el usuario y la aplicación tienen. Por ejemplo, si se ha concedido permiso a la aplicación para escribir el contenido de un repositorio, pero el usuario solo puede leerlo, el token de acceso de usuario solo puede leer el contenido.

Del mismo modo, un token de acceso de usuario solo puede acceder a los recursos a los que el usuario y la aplicación pueden acceder. Por ejemplo, si se concede acceso a una aplicación al repositorio A y B, y el usuario puede acceder al repositorio B y C, el token de acceso de usuario puede acceder al repositorio B, pero no A ni a C. Puedes usar la API REST para comprobar a qué instalaciones y qué repositorios de una instalación puede acceder un token de acceso de usuario. Para más información, consulta GET /user/installations y GET /user/installations/{installation_id}/repositories en "Instalaciones de aplicaciones de GitHub".

Al realizar solicitudes de API con un token de acceso de usuario, se aplican los límites de frecuencia de los tokens de acceso de usuario. Para obtener más información, vea «Límites de frecuencia para aplicaciones de GitHub».

De manera predeterminada, el token de acceso de usuario expira después de ocho horas. Puedes usar un token de actualización para regenerar un token de acceso de usuario. Para obtener más información, vea «Actualización de tokens de acceso de usuario».

Los usuarios pueden revocar su autorización de una instancia de GitHub App. Para obtener más información, vea «Vencimiento y revocación de tokens». Si un usuario revoca su autorización de una instancia de GitHub App, la aplicación recibirá el webhook github_app_authorization. Las instancias de GitHub Apps no pueden cancelar la suscripción a este evento. Si la aplicación recibe este webhook, debes dejar de llamar a la API en nombre del usuario que ha revocado el token. Si la aplicación sigue usando un token de acceso revocado, recibirá el error 401 Bad Credentials. Para más información sobre este webhook, consulta "Eventos y cargas de webhook".

Debes mantener protegidos los tokens de acceso de usuario y los tokens de actualización. Para obtener más información, vea «Procedimientos recomendados para crear una aplicación de GitHub».

Uso del flujo de aplicación web para generar un token de acceso de usuario

Si la aplicación se ejecuta en el explorador, debes usar el flujo de aplicación web para generar un token de acceso de usuario. Para ver un tutorial sobre el uso del flujo de aplicaciones web, consulta "Creación de un botón "Inicio de sesión con GitHub" con una aplicación de GitHub".

Dirige al usuario a esta URL y agrega los parámetros de consulta necesarios de la siguiente lista de parámetros: https://github.com/login/oauth/authorize. Por ejemplo, esta URL especifica los parámetros client_id y state: https://github.com/login/oauth/authorize?client_id=12345&state=abcdefg.

Parámetro de consulta	Tipo	Descripción
`client_id`	`string`	Obligatorio. El id. de cliente de la instancia de GitHub App. El id. de cliente es diferente del id. de la aplicación. Puedes encontrar el id. de cliente en la página de configuración de la aplicación. En el caso de las aplicaciones propiedad del usuario, la página de configuración es `https://github.com/settings/apps/APP-SLUG`. En el caso de las aplicaciones propiedad de la organización, la página de configuración es `https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG`. Reemplaza `APP-SLUG` por el nombre con slug de la aplicación y `ORGANIZATION` por el nombre con slug de la organización. Por ejemplo, `https://github.com/organizations/octo-org/settings/apps/octo-app`.
`redirect_uri`	`string`	La URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Debe ser una coincidencia exacta con una de las URL que has proporcionado como "Dirección URL de devolución de llamada" en la configuración de la aplicación y no puede contener ningún parámetro adicional.
`state`	`string`	Si se especifica, el valor debe contener una cadena aleatoria para la protección contra ataques de falsificación, y también contener otros datos arbitrarios.
`login`	`string`	Si se especifica, el flujo de aplicación web solicitará a los usuarios una cuenta específica que puedan usar para iniciar sesión y autorizar la aplicación.
`allow_signup`	`boolean`	Con independencia de que se ofrezca a los usuarios no autenticados una opción para que se registren en GitHub durante el flujo de OAuth. El valor predeterminado es `true`. Use `false` cuando una directiva prohíba los registros.

Si el usuario acepta la solicitud de autorización, GitHub redirigirá al usuario a una de las URL de devolución de llamada de la configuración de la aplicación y proporcionará un parámetro de consulta code que puedes usar en el paso siguiente para crear un token de acceso de usuario. Si en el paso anterior has especificado redirect_uri, se usará esa URL de devolución de llamada. De lo contrario, se usará la primera URL de devolución de llamada de la página de configuración de la aplicación.

Si has especificado el parámetro state en el paso anterior, GitHub también incluirá un parámetro state. Si el parámetro state no coincide con el parámetro state que has enviado en el paso anterior, no se puede confiar en la solicitud y se debe anular el flujo de la aplicación web.

Cambia el valor code del paso anterior para un token de acceso de usuario mediante la realización de una solicitud POST a esta dirección URL, junto con los parámetros de consulta siguientes: https://github.com/login/oauth/access_token

Parámetro de consulta	Tipo	Descripción
`client_id`	`string`	Obligatorio. El id. de cliente de la instancia de GitHub App. El id. de cliente es diferente del id. de la aplicación. Puedes encontrar el id. de cliente en la página de configuración de la aplicación. En el caso de las aplicaciones propiedad del usuario, la página de configuración es `https://github.com/settings/apps/APP-SLUG`. En el caso de las aplicaciones propiedad de la organización, la página de configuración es `https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG`. Reemplaza `APP-SLUG` por el nombre con slug de la aplicación y `ORGANIZATION` por el nombre con slug de la organización. Por ejemplo, `https://github.com/organizations/octo-org/settings/apps/octo-app`.
`client_secret`	`string`	Obligatorio. El secreto de cliente de GitHub App. Puedes generar un secreto de cliente en la página de configuración de la aplicación.
`code`	`string`	Obligatorio. El código que has recibido en el paso anterior.
`redirect_uri`	`string`	La URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Debe ser una coincidencia exacta con una de las URL que has proporcionado como "Dirección URL de devolución de llamada" al configurar GitHub App y no puede contener ningún parámetro adicional.
`repository_id`	`string`	Identificador de un único repositorio al que puede acceder el token de acceso de usuario. Si la GitHub App o el usuario no pueden acceder al repositorio, se omitirá. Usa este parámetro para restringir aún más el acceso del token de acceso de usuario.

GitHub responderá con una respuesta que incluye los parámetros siguientes:

Parámetro de respuesta	Tipo	Descripción
`access_token`	`string`	Token de acceso de usuario. El token comienza con `ghu_`.
`expires_in`	`integer`	Número de segundos hasta que `access_token` expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será `28800` (8 horas).
`refresh_token`	`string`	El token de actualización. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El token comienza con `ghr_`.
`refresh_token_expires_in`	`integer`	Número de segundos hasta que `refresh_token` expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será `15811200` (6 meses).
`scope`	`string`	Ámbitos que tiene el token. Este valor siempre será una cadena vacía. A diferencia de un token de OAuth tradicional, el token de acceso de usuario se limita a los permisos que tienen tanto la aplicación como el usuario.
`token_type`	`string`	Tipo de token. El valor siempre será `bearer`.

Usa el token de acceso de usuario del paso anterior para realizar solicitudes de API en nombre del usuario. Incluye el token de acceso de usuario en el encabezado Authorization de una solicitud de API. Por ejemplo:
```
curl --request GET \
--url "https://api.github.com/user" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer USER_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"
```

Uso del flujo de dispositivos para generar un token de acceso de usuario

Nota: El flujo de dispositivos se encuentra en versión beta pública y está sujeto a cambios.

Si la aplicación no tiene encabezado ni acceso a un explorador, debes usar el flujo de dispositivos para generar un token de acceso de usuario. Por ejemplo, las herramientas de la CLI, Raspberry Pis simples y las aplicaciones de escritorio deben usar el flujo de dispositivo. Para un tutorial que usa el flujo de dispositivo, consulta "Creación de una CLI con una aplicación de GitHub".

Antes de que puedas utilizar el flujo de dispositivos, primero debes habilitarlo en la configuración de la aplicación. Para más información sobre cómo habilitar el flujo de dispositivos, consulta "Modifying a GitHub App registration".

En el flujo de dispositivos se usa la concesión de autorización de dispositivos de OAuth 2.0.

Envía una solicitud POST a https://github.com/login/device/code junto con un parámetro de consulta client_id. El id. de cliente es diferente del id. de la aplicación. Puedes encontrar el id. de cliente en la página de configuración de la aplicación.
- En el caso de las aplicaciones propiedad del usuario, la página de configuración es https://github.com/settings/apps/APP-SLUG.
- En el caso de las aplicaciones propiedad de la organización, la página de configuración es https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.
Reemplaza APP-SLUG por el nombre con slug de la aplicación y ORGANIZATION por el nombre con slug de la organización. Por ejemplo, https://github.com/organizations/octo-org/settings/apps/octo-app.

GitHub dará una respuesta que incluirá los parámetros de consulta siguientes:

Parámetro de respuesta	Tipo	Descripción
`device_code`	`string`	Código de verificación que se usa para comprobar el dispositivo. Este código tiene 40 caracteres de longitud.
`user_code`	`string`	Código de verificación que la aplicación debe mostrar para que el usuario pueda escribir el código en un explorador. El código es de 8 caracteres con un guión medio a la mitad. Por ejemplo: `WDJB-MJHT`.
`verification_uri`	`string`	Dirección URL donde los usuarios deben escribir su `user_code`. La URL es: `https://github.com/login/device`.
`expires_in`	`integer`	Número de segundos antes de que `device_code` y `user_code` expiren. El valor predeterminado es de 900 segundos (15 minutos).
`interval`	`integer`	Número mínimo de segundos que deben pasar antes de poder realizar una nueva solicitud de token de acceso (`POST https://github.com/login/oauth/access_token`) para completar la autorización del dispositivo. Si realizas una solicitud antes de que se supere este intervalo, alcanzarás el límite de frecuenta y se producirá un error `slow_down`. El valor predeterminado es 5 segundos.

Pide al usuario que escriba el valor user_code del paso anterior en https://github.com/login/device.

Si el usuario no escribe el código antes de que pase el tiempo expires_in, el código no será válido. En este caso, debes reiniciar el flujo del dispositivo.

Sondea POST https://github.com/login/oauth/access_token junto con los parámetros de consulta client_id, device_code y grant_type (descritos a continuación) hasta que expiren los códigos de dispositivo y usuario, o bien el usuario haya autorizado correctamente la aplicación al escribir user_code.

Parámetro de consulta	Tipo	Descripción
`client_id`	`string`	Obligatorio. El id. de cliente de la instancia de GitHub App.
`device_code`	`string`	Obligatorio. El código de verificación del dispositivo que has recibido en el paso anterior.
`grant_type`	`string`	Obligatorio. El tipo de concesión debe ser `urn:ietf:params:oauth:grant-type:device_code`.
`repository_id`	`string`	Identificador de un único repositorio al que puede acceder el token de acceso de usuario. Si la GitHub App o el usuario no pueden acceder al repositorio, se omitirá. Usa este parámetro para restringir aún más el acceso del token de acceso de usuario.

No sondees este punto de conexión con una frecuencia mayor que la indicada por interval. Si lo haces, alcanzarás el limite de frecuencia y se producirá un error slow_down. La respuesta de error slow_down agrega 5 segundos a la última instancia de interval.

Hasta que el usuario escriba el código, GitHub responderá con un estado 200 y un parámetro de consulta de respuesta error.

Nombre del error	Descripción
`authorization_pending`	Este error ocurre cuando la solicitud de autorización se encuentra pendiente y el usuario no ha ingresado el código de usuario aún. Se espera que la aplicación continúe el sondeo de `POST https://github.com/login/oauth/access_token` con una frecuencia que no sea más rápida que la especificada por `interval`.
`slow_down`	Cuando recibe el error `slow_down`, se agregan 5 segundos adicionales al valor `interval` mínimo o período de tiempo necesario entre las solicitudes mediante `POST https://github.com/login/oauth/access_token`. Por ejemplo, si en el intervalo de inicio se necesitaban al menos 5 segundos entre solicitudes y recibes una respuesta de error `slow_down`, ahora tendrás que esperar al menos 10 segundos antes de poder realizar una nueva solicitud para un token. La respuesta de error incluye el nuevo valor `interval` que debe usar.
`expired_token`	Si el código del dispositivo ha expirado, verá el error `token_expired`. Debes hacer una nueva solicitud para un código de dispositivo.
`unsupported_grant_type`	El tipo de concesión debe ser `urn:ietf:params:oauth:grant-type:device_code` e incluirse como parámetro de entrada al sondear la solicitud de token de OAuth `POST https://github.com/login/oauth/access_token`.
`incorrect_client_credentials`	Para el flujo de dispositivos, debes pasar la ID de cliente de tu app, la cual puedes encontrar en la página de configuración de la misma. El id. de cliente es diferente del id. de la aplicación y el secreto de cliente.
`incorrect_device_code`	El valor `device_code` proporcionado no es válido.
`access_denied`	Cuando un usuario hace clic en Cancelar durante el proceso de autorización, se producirá un error `access_denied` y el usuario no podrá volver a utilizar el código de verificación.
`device_flow_disabled`	El flujo de dispositivos no se habilitó en los ajustes de la app. Para más información sobre cómo habilitar el flujo de dispositivos, consulta "Modifying a GitHub App registration".

Cuando el usuario haya escrito user_code, GitHub dará una respuesta que incluye los siguientes parámetros de consulta:

Parámetro de respuesta	Tipo	Descripción
`access_token`	`string`	Token de acceso de usuario. El token comienza con `ghu_`.
`expires_in`	`integer`	Número de segundos hasta que `access_token` expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será `28800` (8 horas).
`refresh_token`	`string`	El token de actualización. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El token comienza con `ghr_`.
`refresh_token_expires_in`	`integer`	Número de segundos hasta que `refresh_token` expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será `15811200` (6 meses).
`scope`	`string`	Ámbitos que tiene el token. Este valor siempre será una cadena vacía. A diferencia de un token de OAuth tradicional, el token de acceso de usuario se limita a los permisos que tienen tanto la aplicación como el usuario.
`token_type`	`string`	Tipo de token. El valor siempre será `bearer`.

Usa el token de acceso de usuario del paso anterior para realizar solicitudes de API en nombre del usuario. Incluye el token de acceso de usuario en el encabezado Authorization de una solicitud de API. Por ejemplo:
```
curl --request GET \
--url "https://api.github.com/user" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer USER_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"
```

Generación de un token de acceso de usuario cuando un usuario instala la aplicación

Si seleccionas Solicitar autorización de usuario (OAuth) durante la instalación en la configuración de la aplicación, GitHub iniciará el flujo de la aplicación web inmediatamente después de que un usuario instale la aplicación.

Puedes generar un token de acceso de usuario con este método independientemente de si la aplicación está instalada en una cuenta de usuario o en una cuenta de organización. Pero si la aplicación se ha instalado en una cuenta de organización, tendrás que usar el flujo de aplicación web o el de dispositivos a fin de generar un token de acceso de usuario para otros usuarios de la organización.

Cuando un usuario instala la aplicación, GitHub le redirigirá a https://github.com/login/oauth/authorize?client_id=CLIENT_ID, donde CLIENT_ID es el id. de cliente de la aplicación.
Si el usuario acepta la solicitud de autorización, GitHub redirigirá al usuario a la primera URL de devolución de llamada de la configuración de la aplicación y proporcionará un parámetro de consulta code.

Si quieres controlar qué URL de devolución de llamada se usa, no selecciones Solicitar autorización de usuario (OAuth) durante la instalación. En su lugar, dirige a los usuarios por el flujo de aplicación web completo y especifica el parámetro redirect_uri.

Cambia el valor code del paso anterior para un token de acceso de usuario mediante la realización de una solicitud POST a esta dirección URL, junto con los parámetros de consulta siguientes: https://github.com/login/oauth/access_token

Parámetro de consulta	Tipo	Descripción
`client_id`	`string`	Obligatorio. El id. de cliente de la instancia de GitHub App. El id. de cliente es diferente del id. de la aplicación. Puedes encontrar el id. de cliente en la página de configuración de la aplicación. En el caso de las aplicaciones propiedad del usuario, la página de configuración es `https://github.com/settings/apps/APP-SLUG`. En el caso de las aplicaciones propiedad de la organización, la página de configuración es `https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG`. Reemplaza `APP-SLUG` por el nombre con slug de la aplicación y `ORGANIZATION` por el nombre con slug de la organización. Por ejemplo, `https://github.com/organizations/octo-org/settings/apps/octo-app`.
`client_secret`	`string`	Obligatorio. El secreto de cliente de GitHub App. Puedes generar un secreto de cliente en la página de configuración de la aplicación.
`code`	`string`	Obligatorio. El código que has recibido en el paso anterior.
`redirect_uri`	`string`	La URL en tu aplicación a donde se enviará a los usuarios después de la autorización. Debe ser una coincidencia exacta con una de las URL que has proporcionado como "Dirección URL de devolución de llamada" al configurar GitHub App y no puede contener ningún parámetro adicional.
`repository_id`	`string`	Identificador de un único repositorio al que puede acceder el token de acceso de usuario. Si la GitHub App o el usuario no pueden acceder al repositorio, se omitirá. Usa este parámetro para restringir aún más el acceso del token de acceso de usuario.

GitHub responderá con una respuesta que incluye los parámetros siguientes:

Parámetro de respuesta	Tipo	Descripción
`access_token`	`string`	Token de acceso de usuario. El token comienza con `ghu_`.
`expires_in`	`integer`	Número de segundos hasta que `access_token` expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será `28800` (8 horas).
`refresh_token`	`string`	El token de actualización. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El token comienza con `ghr_`.
`refresh_token_expires_in`	`integer`	Número de segundos hasta que `refresh_token` expira. Si deshabilitaste la expiración de los tokens de acceso de usuario, este parámetro se omitirá. El valor siempre será `15811200` (6 meses).
`scope`	`string`	Ámbitos que tiene el token. Este valor siempre será una cadena vacía. A diferencia de un token de OAuth tradicional, el token de acceso de usuario se limita a los permisos que tienen tanto la aplicación como el usuario.
`token_type`	`string`	Tipo de token. El valor siempre será `bearer`.

Usa el token de acceso de usuario del paso anterior para realizar solicitudes de API en nombre del usuario. Incluye el token de acceso de usuario en el encabezado Authorization de una solicitud de API. Por ejemplo:
```
curl --request GET \
--url "https://api.github.com/user" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer USER_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"
```

Uso de un token de actualización para generar un token de acceso de usuario

De manera predeterminada, los tokens de acceso de usuario expiran después de ocho horas. Si recibes un token de acceso de usuario con una expiración, también recibirás un token de actualización. El token de actualización expira después de 6 meses. Puedes usar este token de actualización para regenerar un token de acceso de usuario. Para obtener más información, vea «Actualización de tokens de acceso de usuario».

GitHub recomienda encarecidamente que uses tokens de acceso de usuario que expiren. Si anteriormente has optado por no usar tokens de acceso de usuario que expiran, pero quieres volver a habilitar esta característica, consulta "Activating optional features for GitHub Apps".

Obtener fuentes

Enumerar repositorios accesibles para el token de acceso del usuario

Enumerar eventos de incidencias

Línea de tiempo del Informe de Problemas

Enumerar eventos de escala de tiempo para una incidencia

Crear un evento de envío de un repositorio

Generación de un token de acceso de usuario para una aplicación de GitHub

En este artículo