Skip to main content

Autenticación en la API REST

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

Puedes encontrar el Id. de cliente y generar un secreto de cliente en la página de configuración de la aplicación. Para más información sobre cómo desplazarte a la página de configuración en tu GitHub App, consulta "Modificación del registro de una instancia de GitHub App".

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