Authentifizieren bei der REST-API

Informationen zur Authentifizierung

Viele REST-API-Endpunkte erfordern die Authentifizierung oder geben im Fall einer Authentifizierung zusätzliche Informationen zurück. Darüber hinaus können Sie mehr Anforderungen pro Stunde stellen, wenn Sie authentifiziert sind.

Um Ihre Anforderung zu authentifizieren, müssen Sie ein Authentifizierungstoken mit den erforderlichen Bereichen oder Berechtigungen bereitstellen. Es gibt verschiedene Möglichkeiten zum Abrufen eines Tokens: Sie können ein personal access token erstellen, ein Token mit einem GitHub App generieren oder den integrierten GITHUB_TOKEN in einem GitHub Actions-Workflow verwenden.

Nachdem Sie ein Token erstellen, können Sie eine Anforderung authentifizieren, indem Sie ein Token im Authorization-Header Ihrer Anforderung senden. Zum Beispiel können Sie im folgenden Beispiel YOUR-TOKEN durch einen Verweis auf Ihr Token ersetzen:

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

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.

Wenn Sie versuchen, einen REST-API-Endpunkt ohne ein Token oder mit einem Token zu verwenden, das über unzureichende Berechtigungen verfügt, wird die Meldung 404 Not Found oder 403 Forbidden zurückgegeben. Bei der Authentifizierung mit ungültigen Anmeldeinformationen wird anfänglich eine 401 Unauthorized-Antwort zurückgegeben.

Nach der Erkennung mehrerer Anforderungen mit ungültigen Anmeldeinformationen innerhalb eines kurzen Zeitraums lehnt die API vorübergehend alle Authentifizierungsversuche für diesen Benutzerin (auch Benutzer*innen mit gültigen Anmeldeinformationen) mit einer 403 Forbidden-Antwort ab. Weitere Informationen finden Sie unter Ratenbegrenzungen für die REST-API.

Authentifizieren mit einem personal access token

Wenn Sie die GitHub-REST-API für den privaten Gebrauch nutzen möchten, können Sie ein personal access token erstellen. Wenn möglich, empfiehlt GitHub, dass Sie fine-grained personal access token anstelle von personal access token (classic) verwenden. Weitere Informationen zum Erstellen eines personal access tokens findest du unter Verwalten deiner persönlichen Zugriffstoken.

Wenn Sie eine fine-grained personal access token verwenden, benötigt Ihr fine-grained personal access token bestimmte Berechtigungen, um auf jeden REST-API-Endpunkt zuzugreifen. Das REST-API-Referenzdokument für jeden Endpunkt gibt an, ob der Endpunkt zusammen mit fine-grained personal access token funktioniert und welche Berechtigungen erforderlich sind, damit das Token den Endpunkt verwenden kann. Einige Endpunkte erfordern möglicherweise mehrere Berechtigungen und einige möglicherweise eine von mehreren Berechtigungen. Eine Übersicht über die Endpunkte der REST-API, auf die ein fine-grained personal access token mit den einzelnen Berechtigungen zugreifen kann, findest du unter Erforderliche Berechtigungen für differenzierte persönliche Zugangstoken.

Wenn Sie eine personal access token (classic) verwenden, sind bestimmte Bereiche erforderlich, um auf jeden REST-API-Endpunkt zuzugreifen. Allgemeine Informationen zu den zu wählenden Bereichen findest du unter Bereiche für OAuth-Apps.

Personal access tokens fungieren als deine Identität (begrenzt durch die Bereiche oder Berechtigungen, die du ausgewählt hast), wenn du Anforderungen an die REST-API sendest. Daher ist es wichtig, deine personal access tokens sicher zu halten. Um mehr darüber zu erfahren, wie du deine personal access tokens schützen kannst, sieh dir Schützen deiner API-Anmeldeinformationen an.

Personal access tokens und SAML SSO

Authentifizieren mit einem von einer App generierten Token

Wenn Sie die API für eine Organisation oder im Namen anderer Benutzer*innen verwenden möchten, empfiehlt GitHub, dass Sie eine GitHub App verwenden. Weitere Informationen finden Sie unter Informationen zur Authentifizierung mit einer GitHub-App.

Die REST-API-Referenzdokumentation für jeden Endpunkt gibt an, ob der Endpunkt zusammen mit GitHub Apps funktioniert und welche Berechtigungen erforderlich sind, damit die App den Endpunkt verwenden kann. Einige Endpunkte erfordern möglicherweise mehrere Berechtigungen und einige möglicherweise eine von mehreren Berechtigungen. Eine Übersicht über die Endpunkte der REST-API, auf die eine GitHub App mit den einzelnen Berechtigungen zugreifen kann, findest du unter Erforderliche Berechtigungen für GitHub Apps.

Sie können auch ein OAuth-Token mit einer OAuth app erstellen, um auf die REST-API zuzugreifen. GitHub empfiehlt jedoch, stattdessen eine GitHub App zu verwenden. GitHub Apps ermöglichen eine bessere Kontrolle über den Zugriff und die Berechtigungen, die die App hat.

Verwenden der Standardauthentifizierung

Für einige REST-API-Endpunkte für GitHub Apps und OAuth apps müssen Sie die Standardauthentifizierung für den Zugriff auf den Endpunkt verwenden. Sie verwenden die Client-ID der App als Benutzernamen und den geheimen Clientschlüssel der App als Kennwort.

Zum Beispiel:

curl --request POST \
--url "http(s)://HOSTNAME/api/v3/applications/YOUR_CLIENT_ID/token" \
--user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--data '{
  "access_token": "ACCESS_TOKEN_TO_CHECK"
}'

Die Client-ID und der geheime Clientschlüssel sind mit der App verknüpft, nicht mit dem Besitzer der App oder einem Benutzer/einer Benutzerin, der/die die App autorisiert hat. Sie werden verwendet, um Vorgänge im Namen der Anwendung auszuführen, wie z. B. die Erstellung von Zugriffstokens.

Wenn Sie Besitzerin einer GitHub App oder OAuth app oder App-Managerin für eine GitHub App sind, können Sie die Client-ID finden und einen geheimen Clientschlüssel auf der Einstellungsseite für Ihre App generieren. So navigieren Sie zur Einstellungsseite Ihrer App:

Klicke in der oberen rechten Ecke einer beliebigen Seite auf GitHub auf dein Profilfoto.
Navigieren Sie zu den Einstellungen für Ihr Konto.
- Klicken Sie bei einer App, die zu einem persönlichen Konto gehört, auf Einstellungen.
- Für eine App im Besitz einer Organisation:
  1. Klicke Sie auf Ihre Organisationen.
  2. Klicke dann rechts neben der Organisation auf Einstellungen.
Klicke in der linken Randleiste auf Developer settings.
Klicken Sie in der linken Randleiste auf GitHub Apps oder OAuth apps.
Klicken Sie für GitHub Apps rechts neben den GitHub App, auf die Sie zugreifen möchten, auf Bearbeitung. Klicken Sie bei OAuth apps auf die App, auf die Sie zugreifen möchten.
Neben der Client-ID wird die Client-ID für Ihre App angezeigt.

       **Klicken Sie neben geheimen Clientschlüsseln** auf **Neuen geheimen Clientschlüssel** generieren, um einen geheimen Clientschlüssel für Ihre App zu generieren.

Authentifizieren in einem GitHub Actions Workflow

Wenn Sie die API in einem GitHub Actions Workflow verwenden möchten, empfiehlt GitHub, dass Sie sich mit dem integrierten GITHUB_TOKEN authentifizieren, anstatt ein Token zu erstellen. Sie können mit dem Schlüssel GITHUB_TOKEN dem permissions Berechtigungen erteilen. Weitere Informationen finden Sie unter Verwenden von GITHUB_TOKEN für die Authentifizierung in Workflows.

Wenn dies nicht möglich ist, können Sie Ihr Token als geheimen Schlüssel speichern und den Namen Ihres geheimen Schlüssels in Ihrem GitHub Actions Workflow verwenden. Weitere Informationen zu Geheimnissen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

Authentifizierung in einem GitHub Actions Workflow unter Verwendung von GitHub CLI

Um eine authentifizierte Anforderung an die API in einem GitHub Actions Workflow mithilfe von GitHub CLI durchzuführen, können Sie den Wert von GITHUB_TOKEN als Umgebungsvariable speichern und das Schlüsselwort (keyword) run verwenden, um den Unterbefehl GitHub CLI api auszuführen. Weitere Informationen zum Schlüsselwort run findest du unter Workflowsyntax für GitHub Actions.

Ersetzen Sie PATH im folgenden Beispielworkflow durch den Pfad des Endpunkts. Weitere Informationen zum Pfad findest du unter Erste Schritte mit der REST-API. Ersetze HOSTNAME durch den Namen von Ihre GitHub Enterprise Server-Instance.

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api /PATH

Authentifizieren in einem GitHub Actions-Workflow mithilfe von `curl`

Wenn Sie eine authentifizierte Anforderung an die API in einemGitHub Actions Workflow mithilfe von curl senden möchten, können Sie den Wert GITHUB_TOKEN als Umgebungsvariable speichern und das Schlüsselwort (keyword) run verwenden, um eine curl-Anforderung an die API auszuführen. Weitere Informationen zum Schlüsselwort run findest du unter Workflowsyntax für GitHub Actions.

YAML

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

Authentifizieren in einem GitHub Actions-Workflow mithilfe von JavaScript

Ein Beispiel für die Authentifizierung in einem GitHub Actions-Workflow mit JavaScript findest du unter Skripterstellung mit der REST-API und JavaScript.

Authentifizieren mit Benutzername und Kennwort

GitHub empfiehlt die Verwendung eines Tokens anstelle eines Kennworts zur Authentifizierung bei der REST-API. Sie haben mehr Kontrolle darüber, was ein Token tun kann, und Sie können ein Token jederzeit widerrufen. Sie können sich jedoch auch bei der REST-API authentifizieren, indem Sie Ihren Benutzernamen und Ihr Kennwort für die Standardauthentifizierung verwenden. Übergeben Sie hierfür Ihren Benutzernamen und Ihr Kennwort mit der --user-Option:

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/user" \
--user USERNAME:PASSWORD \
--header "X-GitHub-Api-Version: 2022-11-28"

Weiterführende Lektüre

        [AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)

        [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#authenticating)

In diesem Artikel