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

Acerca de los tokens de acceso de instalación

Para autenticarte como una instalación de la aplicación, debes generar un token de acceso de instalación. Para obtener más información sobre la autenticación como una instalación de la aplicación, consulta "Autenticación como una instalación de aplicación de GitHub".

Debes mantener el token de acceso de instalación protegido. Para obtener más información, vea «Procedimientos recomendados para crear una aplicación de GitHub».

Generación de un token de acceso de instalación

1. Genera un JSON Web Token (JWT) para la aplicación. Para más información, consulta "Generación de un JSON Web Token (JWT) para una aplicación de GitHub".

2. Consigue el identificador de la instalación con el que deseas autenticarte.

   Si respondes a un evento de webhook, la carga del webhook incluirá el identificador de la instalación.

   También puedes usar la API REST para buscar el identificador de una instalación de la aplicación. Por ejemplo, puedes obtener un identificador de instalación con los puntos de conexión GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation o GET /app/installations. Para obtener más información, consulta "Puntos de conexión de la API de REST para GitHub Apps".

   Puedes encontrar el identificador de aplicación en la página de configuración de la aplicación. El id. de la aplicación es diferente del id. de cliente. Para más información sobre cómo desplazarte a la página de configuración en tu GitHub App, consulta “Modificación del registro de una instancia de GitHub App”.

3. Envía una solicitud de API REST POST a /app/installations/INSTALLATION_ID/access_tokens. Incluye JSON Web Token en el encabezado Authorization de la solicitud. Reemplaza INSTALLATION_ID por el identificador de la instalación con el que deseas autenticarte.

   Por ejemplo, envía esta solicitud curl. Reemplaza INSTALLATION_ID por el identificador de la instalación y JWT por JSON Web Token:

   curl --request POST \
   --url "http(s)://HOSTNAME/api/v3/app/installations/INSTALLATION_ID/access_tokens" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer JWT" \
   --header "X-GitHub-Api-Version: 2022-11-28"
   

   Opcionalmente, puedes utilizar los parámetros de cuerpo repositories o repository_ids para especificar repositorios individuales a los que puede acceder el token de acceso a la instalación. Si no usas repositories o repository_ids para conceder acceso a repositorios específicos, el token de acceso a la instalación tendrá acceso a todos los repositorios a los que se concedió acceso a la instalación. Al token de acceso de instalación no se le puede conceder acceso a los repositorios a los que la instalación no tuvo acceso. Es posible enumerar hasta 500 repositorios.

   Opcionalmente, usa el parámetro de cuerpo permissions para especificar los permisos que debe tener el token de acceso de instalación. Si no se especifica permissions, el token de acceso de instalación tendrá todos los permisos concedidos a la aplicación. No se pueden conceder al token de acceso a la instalación permisos que la aplicación no tenía concedidos.

   Al usar los parámetros permissions para reducir el acceso del token, se aumenta la complejidad de dicho token debido al número de permisos de la solicitud y al número de repositorios a los que tendrá acceso. Si la complejidad es demasiado grande, se recibirá un mensaje de error que indica el número máximo de repositorios que se pueden admitir. En este caso, se deben solicitar menos permisos con el parámetro permissions, utilizar el parámetro repositories o repository_ids para solicitar menos repositorios, o bien instalar la aplicación en repositorios all de su organización.

   La respuesta incluirá un token de acceso de instalación, la hora en que expira el token, los permisos que tiene el token y los repositorios a los que puede acceder el token. El token de acceso de instalación expirará después de 1 hora.

   Para obtener más información sobre este punto de conexión, consulta "Puntos de conexión de la API de REST para GitHub Apps".

   Nota: En la mayoría de los casos, puedes usar Authorization: Bearer o Authorization: token para pasar un token. Sin embargo, si vas a pasar un token web JSON (JWT), debes usar Authorization: Bearer.