Generieren eines Installationszugriffstokens für eine GitHub-App

Informationen zu Installationszugriffstoken

Um dich als App-Installation zu authentifizieren, musst du ein Installationszugriffstoken generieren. Weitere Informationen zur Authentifizierung als App-Installation findest du unter Authentifizieren als GitHub-App-Installation.

Du musst das Installationszugriffstoken sicher aufbewahren. Weitere Informationen findest du unter Best Practices beim Erstellen einer GitHub-App.

Generieren eines Installationszugriffstokens:

1. Generiere ein JSON-Webtoken (JWT) für deine App. Weitere Informationen findest du unter Generieren eines JSON Web Token (JWT) für eine GitHub-App.

2. Ruf die ID der Installation ab, als die du dich authentifizieren möchtest.

   Wenn du auf ein Webhookereignis reagierst, enthält die Webhooknutzlast die Installations-ID.

   Du kannst auch die REST-API verwenden, um die ID für eine Installation deiner App zu ermitteln. Eine Installations-ID kannst du z. B. mit den Endpunkten GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation oder GET /app/installations abrufen. Weitere Informationen findest du unter REST-API-Endpunkte für GitHub Apps.

   Sie finden die App-ID auch auf der Einstellungsseite Ihrer App. Die App-ID unterscheidet sich von der Client-ID. Weitere Informationen zum Aufrufen der Einstellungsseite für Ihre GitHub App finden Sie unter „Ändern einer GitHub-App-Registrierung“.

3. Sende eine REST-API-POST-Anforderung an /app/installations/INSTALLATION_ID/access_tokens. Fügen dein JSON-Webtoken in den Authorization-Header deiner Anforderung ein. Ersetze INSTALLATION_ID durch die ID der Installation, als die du dich authentifizieren möchtest.

   Sende beispielsweise diese cURL-Anforderung. Ersetze INSTALLATION_ID durch die ID der Installation und JWT durch dein JSON-Webtoken:

   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"
   

   Optional kannst du den Textparameter repositories oder repository_ids verwenden, um einzelne Repositorys anzugeben, auf die das Installationszugriffstoken zugreifen kann. Wenn du nicht repositories oder repository_ids verwendest, um Zugriff auf bestimmte Repositorys zu gewähren, hat das Installationszugriffstoken Zugriff auf alle Repositorys, auf die der Installation Zugriff gewährt wurde. Dem Installationszugriffstoken kann kein Zugriff auf Repositorys gewährt werden, auf die die Installation keinen Zugriff gewährt wurde. Sie können bis zu 500 Repositorys auflisten.

   Verwende optional den Textparameter permissions, um die Berechtigungen anzugeben, die das Installationszugriffstoken haben soll. Wenn permissions nicht angegeben ist, verfügt das Installationszugriffstoken über alle Berechtigungen, die der App gewährt wurden. Dem Installationszugriffstoken können keine Berechtigungen gewährt werden, die der App nicht erteilt wurden.

   Wenn Sie die permissions-Parameter verwenden, um den Zugriff auf das Token zu verringern, wird die Komplexität des Tokens aufgrund der Anzahl der Berechtigungen in der Anforderung erhöht, und die Anzahl der Repositorys, auf die das Token zugreifen kann. Wenn die Komplexität zu groß ist, erhalten Sie eine Fehlermeldung, die die maximale Anzahl von Repositorys angibt, die unterstützt werden können. In diesem Fall sollten Sie weniger Berechtigungen mit dem permissions-Parameter anfordern, den repositories- oder repository_ids-Parameter verwenden, um weniger Repositorys anzufordern oder die App in all-Repositorys in Ihrer Organisation installieren.

   Die Antwort enthält ein Installationszugriffstoken, den Zeitpunkt, zu dem das Token abläuft, die Berechtigungen des Tokens und die Repositorys, auf die das Token zugreifen kann. Das Installationszugriffstoken läuft nach 1 Stunde ab.

   Weitere Informationen zu diesem Endpunkt findest du unter REST-API-Endpunkte für GitHub Apps.

   Hinweis: In den meisten Fällen kannst du Authorization: Bearer oder Authorization: token verwenden, um ein Token zu übergeben. Wenn du jedoch ein JWT (JSON Web Token) übergibst, musst du Authorization: Bearer verwenden.