Autenticación en la API REST

En este artículo

Puedes autenticarte en la API REST para acceder a más puntos de conexión y tener un límite de frecuencia más alto.

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 "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

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. Si es posible, GitHub recomienda el uso de una instancia de fine-grained personal access token en lugar de personal access token (classic). Para más información sobre cómo crear una instancia de personal access token, consulta "Administración de tokens de acceso personal".

Si usa un fine-grained personal access token, sus fine-grained personal access token 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 necesarios para los tokens de acceso personal específicos". Si usa un personal access token (classic), su personal access token (classic) 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".

Si usas una instancia de personal access token (classic) para acceder a una organización que exija el inicio de sesión único (SSO) de SAML para la autenticación, tendrás que autorizar el token después de la creación.Las instancias de Fine-grained personal access token se autorizan durante la creación de tokens, antes de conceder acceso a la organización. Para más información, consulta "Autorizar un token de acceso personal para usar con un inicio de sesión único de SAML".

Si no autorizas las instancias de personal access token (classic) para el inicio de sesión único de SAML antes de intentar usarlo para acceder a una organización que aplique el inicio de sesión único de SAML, es posible que se genere un error 404 Not Found o 403 Forbidden. Si se produce un error 403 Forbidden, puedes seguir la URL del encabezado X-GitHub-SSO para autorizar el token. La URL caduca después de una hora. Si has solicitado datos que podrían provenir de varias organizaciones, la API no devolverá resultados de las organizaciones en las que se necesite el inicio de sesión único de SAML. El encabezado X-GitHub-SSO indicará el id. de las organizaciones en las que se necesita la autorización de inicio de sesión único de SAML de la instancia de personal access token (classic). Por ejemplo: X-GitHub-SSO: partial-results; organizations=21955855,20582480.

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.

Los tokens de acceso creados por las aplicaciones se autorizan automáticamente para el inicio de sesión único de SAML.

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 "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"
}'

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:

  1. En la esquina superior derecha de cualquier página en GitHub, haga clic en su fotografía de perfil.
  2. 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:
      1. Haga clic en Sus organizaciones.
      2. A la derecha de la organización, haga clic en Configuración.
  3. En la barra lateral izquierda, haz clic en Configuración del desarrollador.
  4. En la barra lateral izquierda, haga clic en GitHub Apps o OAuth apps.
  5. 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.
  6. Junto a Id. de cliente, verá el Id. de cliente de la aplicación.
  7. 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

No se admite la autenticación con nombre de usuario y contraseña. Si intentas autenticarte con el nombre de usuario y la contraseña, se producirá un error 4xx.

Información adicional