Acerca de la autenticación
Muchos puntos de conexión de la API REST necesitan autenticación o devuelven información adicional si te autenticas. Además, cuando te autenticas, puedes realizar más solicitudes por hora.
Para autenticar la solicitud, envía un token en el encabezado Authorization de la solicitud. En el ejemplo siguiente, reemplaza YOUR-TOKEN por una referencia al token:
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"
Nota: En la mayoría de los casos, puedes usar Authorization: Bearer o Authorization: token para pasar un token. Sin embargo, si vas a pasar un token web JSON (JWT), debes usar Authorization: Bearer.
Si intentas usar un punto de conexión de la API REST sin un token o con un token que no tenga permisos suficientes, recibirás una respuesta 404 Not Found o 403 Forbidden.
Autenticación con un personal access token
Si quieres utilizar la API REST de GitHub para uso personal, puedes crear una instancia de personal access token. Para más información sobre cómo crear una instancia de personal access token, consulta "Administración de tokens de acceso personal".
Sus personal access token requieren ámbitos específicos para acceder a cada punto de conexión de la API de REST. Para obtener instrucciones generales sobre qué ámbitos elegir, consulte "Ámbitos para las aplicaciones de OAuth".
Autenticación con un token generado por una aplicación
Si quieres usar la API para una organización o en nombre de otro usuario, en GitHub se recomienda el uso de una instancia de GitHub App. Para obtener más información, vea «Acerca de la autenticación con una aplicación de GitHub».
Sus GitHub App requieren permisos específicos para acceder a cada punto de conexión de la API de REST. Para obtener más información sobre los permisos necesarios para cada punto de conexión, consulte "Permisos que requieren las Github Apps".
También puedes crear un token de OAuth con una OAuth app para acceder a la API REST. Pero en GitHub se recomienda usar una GitHub App en su lugar. Las GitHub Apps permiten un mayor control sobre el acceso y el permiso que la aplicación.
Uso de autenticación básica
En algunos puntos de conexión de API de REST de las GitHub Apps y OAuth apps es necesario usar la autenticación básica para acceder al punto de conexión. Usarás el Id. de cliente de la aplicación como nombre de usuario y el secreto de cliente como contraseña.
Por ejemplo:
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"
}'
El identificador de cliente y el secreto de cliente están asociados a la aplicación, no al propietario de la aplicación o a un usuario que autorizó la aplicación. Se usan para realizar operaciones en nombre de la aplicación, como la creación de tokens de acceso.
Si es el propietario de un GitHub App o OAuth app, o si es administrador de aplicaciones para un GitHub App, puede encontrar el Id. de cliente y generar un secreto de cliente en la página de configuración de la aplicación. Para ir a la página de configuración de la aplicación:
- En la esquina superior derecha de cualquier página en GitHub Enterprise Server, haga clic en su fotografía de perfil.
- Navega a la configuración de tu cuenta.
- Para una aplicación propiedad de una cuenta personal, haga clic en Configuración.
- Para una aplicación propiedad de una organización:
- Haga clic en Sus organizaciones.
- A la derecha de la organización, haga clic en Configuración.
- En la barra lateral izquierda, haz clic en Configuración del desarrollador.
- En la barra lateral izquierda, haga clic en GitHub Apps o OAuth apps.
- Para GitHub Apps, a la derecha de GitHub App a los que desea acceder, haga clic en Editar. Para OAuth apps, haga clic en la aplicación a la que desea acceder.
- Junto a Id. de cliente, verá el Id. de cliente de la aplicación.
- Junto a Secretos de cliente, haga clic en Generar un nuevo secreto de cliente para generar un secreto de cliente para la aplicación.
Autenticación en un flujo de trabajo de GitHub Actions
Si deseas usar la API en un flujo de trabajo de GitHub Actions, GitHub recomienda autenticarse con el GITHUB_TOKEN integrado en lugar de crear un token. Puedes conceder permisos a GITHUB_TOKEN con la clave permissions. Para obtener más información, vea «Autenticación automática de tokens».
Autenticación con nombre de usuario y contraseña
En GitHub se recomienda usar un token para autenticarse en la API REST en lugar de la contraseña. Tienes más control sobre lo que puede hacer un token y puedes revocar un token en cualquier momento. Pero también te puedes autenticar en la API REST mediante el nombre de usuario y la contraseña para la autenticación básica. Para ello, tendrás que pasar el nombre de usuario y la contraseña con la opción --user:
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/user" \
--user USERNAME:PASSWORD