Génération d’un jeton d’accès d’installation pour une application GitHub

À propos des jetons d’accès d’installation

Pour vous authentifier en tant qu’installation d’application, vous devez générer un jeton d’accès d’installation. Pour plus d’informations sur l’authentification en tant qu’installation d’application, consultez « Authentification en tant qu’application GitHub ».

Vous devez conserver votre jeton d’accès d’installation en sécurité. Pour plus d’informations, consultez « Meilleures pratiques pour la création d’une application GitHub ».

Génération d’un jeton d’accès d’installation

1. Générez un jeton web JSON (JWT) pour votre application. Pour plus d’informations, consultez « Génération d’un jeton web JSON (JWT) pour une application GitHub ».

2. Obtenez l’ID de l’installation que vous souhaitez utiliser pour l’authentification.

   Si vous répondez à un événement de webhook, la charge utile du webhook inclut l’ID d’installation.

   Vous pouvez également utiliser l’API REST pour rechercher l’ID d’une installation de votre application. Par exemple, vous pouvez obtenir un ID d’installation avec les points de terminaison GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation ou GET /app/installations. Pour plus d’informations, consultez « Points de terminaison d’API REST pour GitHub Apps ».

   Vous pouvez également trouver l’ID d’application dans la page de paramètres de votre application. L’ID de l’application n’est pas l’ID client. Pour plus d’informations sur la navigation vers la page des paramètres pour votre GitHub App, consultez « Modification d’une inscription d’application GitHub ».

3. Envoi d’une requête d’API REST POST à /app/installations/INSTALLATION_ID/access_tokens. Incluez votre jeton web JSON dans l’en-tête Authorization de votre requête. Remplacez INSTALLATION_ID par l’ID de l’installation que vous souhaitez utiliser pour l’authentification.

   Par exemple, envoyez cette requête curl. Remplacez INSTALLATION_ID par l’ID de l’installation et JWT par votre jeton web JSON :

   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"
   

   Si vous le souhaitez, vous pouvez utiliser les paramètres de corps repositories ou repository_ids pour spécifier les dépôts individuels auxquels le jeton d’accès d’installation peut accéder. Si vous n’utilisez pas repositories ou repository_ids pour accorder l’accès à des dépôts spécifiques, le jeton d’accès d’installation aura accès à tous les dépôts auxquels l’installation a obtenu l’accès. Le jeton d’accès d’installation ne peut pas être accordé aux référentiels auxquels l’installation n’a pas accordé l’accès. Vous pouvez répertorier jusqu’à 500 référentiels.

   Si vous le souhaitez, utilisez le paramètre de corps permissions pour spécifier les autorisations dont doit disposer le jeton d’accès d’installation. Si permissions n’est pas spécifié, le jeton d’accès d’installation aura toutes les autorisations qui ont été accordées à l’application. Impossible d’accorder au jeton d’accès d’installation des autorisations qui n’ont pas été accordées à l’application.

   Lorsque l'on utilise les paramètres permissionspour réduire l'accès au jeton, la complexité du jeton est augmentée en raison du nombre de permissions dans la requête et du nombre de dépôts auxquels le jeton aura accès. Si cette complexité apparaît trop prononcée, vous recevrez un message d'erreur qui vous indiquera le nombre maximum de référentiels pouvant être pris en charge. Dans ce cas, vous devez demander moins d’autorisations avec le paramètre permissions, utiliser le paramètre repositories ou repository_ids pour demander moins de référentiels, ou installer l’application sur les référentiels all de votre organisation.

   La réponse inclut un jeton d’accès d’installation, l’heure d’expiration du jeton, les autorisations dont dispose le jeton et les dépôts auxquels le jeton peut accéder. Le jeton d’accès d’installation expire après 1 heure.

   Pour plus d’informations sur ce point de terminaison, consultez « Points de terminaison d’API REST pour GitHub Apps ».

   Note

   Dans la plupart des cas, vous pouvez utiliser Authorization: Bearer ou Authorization: token pour passer un jeton. Toutefois, si vous passez un jeton web JSON (JWT), vous devez utiliser Authorization: Bearer.