À 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é.
Vous pouvez authentifier votre requête en envoyant un jeton dans l’en-tête Authorization de votre requête. Dans l’exemple suivant, remplacez YOUR-TOKEN par une référence à votre jeton :
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"
Remarque : 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.
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.
Authentification avec un personal access token
Si vous souhaitez utiliser l’API REST GitHub à des fins personnelles, vous pouvez créer un personal access token. Pour plus d’informations sur la création d’un personal access token, consultez « Gestion de vos jetons d’accès personnels ».
Votre personal access token nécessite des étendues spécifiques afin d’accéder à chaque point de terminaison d’API REST. Pour obtenir des conseils généraux sur les étendues à choisir, consultez « Étendues des applications OAuth ».
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 ».
Votre GitHub App nécessite des autorisations spécifiques afin d’accéder à chaque point de terminaison d’API REST. Pour plus d’informations sur les autorisations requises pour chaque point de terminaison, 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.
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 "http(s)://HOSTNAME/api/v3/applications/YOUR_CLIENT_ID/token" \
--user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"
--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 :
- Dans le coin supérieur droit de n’importe quelle page sur GitHub, cliquez sur votre photo de profil.
- 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 :
- Cliquez sur Vos organisations.
- À droite de l’organisation, cliquez sur Paramètres.
- Dans la barre latérale gauche, cliquez sur Paramètres de développeur.
- Dans la barre latérale gauche, cliquez sur GitHub Apps ou OAuth apps.
- 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.
- En regard de l’ID client vous verrez l’ID client de votre application.
- 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 ».
Authentification avec un nom d’utilisateur et un mot de passe
GitHub vous recommande d’utiliser un jeton pour vous authentifier auprès de l’API REST au lieu de votre mot de passe. Vous avez davantage de contrôle sur ce qu’un jeton peut faire et vous pouvez révoquer un jeton à tout moment. Toutefois, vous pouvez également vous authentifier auprès de l’API REST avec votre nom d’utilisateur et votre mot de passe pour l’authentification de base. Pour ce faire, vous transmettez votre nom d’utilisateur et votre mot de passe avec l’option --user :
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/user" \
--user USERNAME:PASSWORD