Skip to main content

Authentification auprès de l’API REST

Vous pouvez vous authentifier auprès de l’API REST pour accéder à davantage de points de terminaison et avoir une limite de débit plus élevée.

À propos de l’authentification

De nombreux points de terminaison de l’API REST nécessitent une authentification ou retournent des informations supplémentaires si vous êtes authentifié. De plus, vous pouvez effectuer plus de requêtes par heure lorsque vous êtes authentifié.

Pour authentifier votre demande, vous devez fournir un jeton d’authenti fication avec les étendues ou autorisations requises. Il existe plusieurs façons d’obtenir un jeton : vous pouvez créer un personal access token, générer un jeton avec un GitHub App, ou utiliser le GITHUB_TOKEN intégré dans un flux de travail GitHub Actions.

Après la création du jeton, vous pouvez authentifier votre demande en envoyant le jeton dans l’en-tête Authorization de votre demande. Par exemple, dans la demande suivante, remplacez YOUR-TOKEN par une référence à votre jeton :

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

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.

Limite d’échecs de connexion

Si vous essayez d’utiliser un point de terminaison de l’API REST sans jeton ou avec un jeton disposant d’autorisations insuffisantes, vous recevez une réponse 404 Not Found ou 403 Forbidden. L’authentification à l’aide d’informations d’identification non valides renvoie initialement une réponse 401 Unauthorized.

Après détection de plusieurs demandes comportant des informations d’identification non valides dans un court délai, l’API rejette temporairement toutes les tentatives d’authentification de cet utilisateur (y compris celles contenant des informations d’identification valides) avec une réponse 403 Forbidden. Pour plus d’informations, consultez « Limites de débit pour l'API REST ».

Authentification avec un personal access token

Si vous voulez utiliser l’API REST GitHub à des fins personnelles, vous pouvez créer un personal access token. Si possible, GitHub vous recommande d’utiliser un fine-grained personal access token à la place d’un personal access token (classic). Pour plus d’informations sur la création d’un personal access token, consultez Gestion de vos jetons d'accès personnels.

Si vous utilisez un fine-grained personal access token, vos fine-grained personal access token nécessitent des autorisations spécifiques pour accéder à chaque point de terminaison de l’API REST. Le document de référence de l’API REST de chaque point de terminaison indique si le point de terminaison fonctionne avec fine-grained personal access token et indique les autorisations requises pour que le jeton utilise le point de terminaison. Certains points de terminaison peuvent nécessiter plusieurs autorisations, et certains points de terminaison peuvent nécessiter une autorisation parmi des autorisations multiples. Pour obtenir une vue d’ensemble des points de terminaison de l’API REST auxquels un fine-grained personal access token peut accéder à chaque autorisation, consultez Autorisations nécessaires pour les jetons d’accès personnels affinés.

Si vous utilisez un personal access token (classic), il nécessite des étendues spécifiques pour accéder à chaque point de terminaison de l’API REST. Pour obtenir des conseils généraux sur les étendues à choisir, consultez Étendues des applications OAuth.

Personal access tokens et SAML SSO

Si vous utilisez un personal access token (classic) pour accéder à une organisation qui applique l’authentification unique SAML (SSO) pour l’authentification, vous devez autoriser votre jeton après la création. Les Fine-grained personal access token sont autorisées lors de la création du jeton, avant l’octroi de l’accès à l’organisation. Pour plus d’informations, consultez « Autorisation d’un jeton d’accès personnel à utiliser avec l’authentification unique SAML ».

Si vous n’autorisez pas votre personal access token (classic) pour l’authentification unique SAML avant d’essayer de l’utiliser pour accéder à une organisation unique qui applique l’authentification unique SAML, vous pouvez recevoir une erreur 404 Not Found ou 403 Forbidden. Si vous recevez une erreur 403 Forbidden, l’en-tête X-GitHub-SSO comprendre une URL que vous pouvez suivre pour autoriser votre jeton. L’URL expire au bout d’une heure.

Si vous n’autorisez pas vos données personal access token (classic) pour l’authentification unique SAML avant de tenter de l’utiliser pour accéder à plusieurs organisations, l’API ne retourne pas les résultats des organisations qui nécessitent l’authentification unique SAML et l’en-tête X-GitHub-SSO indique l’identifiant des organisations qui nécessitent l’autorisation SAML SSO de vos données personal access token (classic). Par exemple : X-GitHub-SSO: partial-results; organizations=21955855,20582480.

Authentification avec un jeton généré par une application

Si vous voulez utiliser l’API pour une organisation ou au nom d’un autre utilisateur, GitHub vous recommande d’utiliser une GitHub App. Pour plus d’informations, consultez « À propos de l’authentification avec une application GitHub ».

La documentation de référence de l’API REST de chaque point de terminaison indique si le point de terminaison fonctionne avec GitHub Apps et indique les autorisations requises pour que l’application utilise le point de terminaison. Certains points de terminaison peuvent nécessiter plusieurs autorisations, et certains points de terminaison peuvent nécessiter une autorisation parmi des autorisations multiples. Pour obtenir une vue d’ensemble des points de terminaison d’API REST auxquels GitHub App peut accéder avec chaque autorisation, consultez Autorisations requises pour les applications GitHub.

Vous pouvez également créer un jeton OAuth avec une OAuth app pour accéder à l’API REST. Toutefois, GitHub vous recommande d’utiliser plutôt une GitHub App. GitHub Apps permettent de mieux contrôler l’accès et les autorisations dont dispose l’application.

Les jetons d’accès créés par les applications sont automatiquement autorisés pour l’authentification unique SAML.

Utilisation de l’authentification de base

Pour y accéder, certains points de terminaison de l’API REST relatifs à GitHub Apps et OAuth apps vous obligent à utiliser une authentification de base. Vous utiliserez l’ID client de l’application comme nom d’utilisateur et le secret client de l’application comme mot de passe.

Par exemple :

curl --request POST \
--url "https://api.github.com/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"
}'

L’ID client et la clé secrète client sont associés à l’application, et non au propriétaire de l’application ou à un utilisateur qui a autorisé l’application. Ils sont utilisés pour effectuer des opérations pour le compte de l’application, telles que la création de jetons d’accès.

Si vous êtes le propriétaire d’une application GitHub App ou OAuth app, ou si vous êtes un manager d’applications pour GitHub App, vous pouvez trouver l’ID client et générer une clé secrète client dans la page paramètres de votre application. Pour accéder à la page des paramètres de votre application :

  1. Dans le coin supérieur droit de n’importe quelle page sur GitHub, cliquez sur votre photo de profil.
  2. Accédez aux paramètres de votre compte.
    • Pour une application appartenant à un compte personnel, cliquez sur Paramètres.
    • Pour une application appartenant à une organisation :
      1. Cliquez sur Vos organisations.
      2. À droite de l'organisation, cliquez sur Paramètres.
  3. Dans la barre latérale gauche, cliquez sur Paramètres de développeur.
  4. Dans la barre latérale gauche, cliquez sur GitHub Apps ou OAuth apps.
  5. Pour GitHub Apps, à droite de GitHub App que vous souhaitez accéder, cliquez sur Modification. Pour OAuth apps, cliquez sur l’application à laquelle vous souhaitez accéder.
  6. En regard de l’ID client vous verrez l’ID client de votre application.
  7. En regard des clés secrètes client, cliquez sur Générer une nouvelle clé secrète client afin de générer une clé secrète client pour votre application.

Authentification dans un workflow GitHub Actions

Si vous voulez utiliser l’API dans un workflow GitHub Actions, GitHub vous recommande d’être authentifié avec le jeton GITHUB_TOKEN intégré au lieu de créer un jeton. Vous pouvez accorder des autorisations au GITHUB_TOKEN avec la clé permissions. Pour plus d’informations, consultez « Authentification par jeton automatique ».

Si ce n’est pas possible, vous pouvez stocker votre jeton en tant que secret et utiliser le nom de votre secret dans votre flux de travail GitHub Actions. Pour plus d’informations sur les secrets, consultez « Utilisation de secrets dans GitHub Actions ».

Authentification dans un flux de travail GitHub Actions à l’aide GitHub CLI

Pour effectuer une demande authentifiée auprès de l’API dans un flux de travail GitHub Actions à l’aide de GitHub CLI, vous pouvez stocker la valeur de GITHUB_TOKEN en tant que variable d’environnement et utiliser le mot clé run pour exécuter la sous-commande api GitHub CLI. Pour plus d’informations sur le mot clé run, consultez « Workflow syntax for GitHub Actions ».

Dans l’exemple de flux de travail suivant, remplacez PATH par le chemin d’accès du point de terminaison. Pour plus d’informations sur le chemin d’accès, consultez Prise en main de l’API REST

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

Authentification dans un flux de travail GitHub Actions à l’aide de curl

Pour effectuer une demande authentifiée auprès de l’API dans un flux de travail GitHub Actions à l’aide de curl, vous pouvez stocker la valeur de GITHUB_TOKEN en tant que variable d’environnement et utiliser le mot clé run pour exécuter une demande curl à l’API. Pour plus d’informations sur le mot clé run, consultez « Workflow syntax for GitHub Actions ».

Dans l’exemple de flux de travail suivant, remplacez PATH par le chemin d’accès du point de terminaison. Pour plus d’informations sur le chemin d’accès, consultez Prise en main de l’API REST

YAML
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

Authentification dans un workflow GitHub Actions à l’aide de JavaScript

Pour obtenir un exemple d’authentification dans un flux de travail GitHub Actions à l’aide de JavaScript, consultez Écriture de scripts avec l’API REST et JavaScript.

Authentification avec un nom d’utilisateur et un mot de passe

L’authentification avec un nom d’utilisateur et un mot de passe n’est pas prise en charge. Si vous essayez de vous authentifier avec un nom d’utilisateur et un mot de passe, vous recevez une erreur 4xx.

Pour aller plus loin