Autenticación en la API REST

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 "Creación de un token de acceso personal".

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 «About authentication with a GitHub App».

También puedes crear un token de OAuth con una instancia de OAuth App para acceder a la API REST. Pero en GitHub se recomienda usar una instancia de GitHub App en su lugar. Las instancias de GitHub App 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 la API REST para instancias de GitHub App y OAuth App es necesario que uses 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/authorizations"
--user CLIENT_ID:CLIENT_SECRET\
--header "X-GitHub-Api-Version: 2022-11-28"

Puedes encontrar el Id. de cliente y generar un secreto de cliente en la página de configuración de la aplicación. En el caso de las instancias de GitHub App propiedad del usuario, la página de configuración es https://github.com/settings/apps/APP-SLUG. En el caso de las instancias de GitHub App propiedad de la organización, la página de configuración es https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG. Reemplaza APP-SLUG por el nombre con slug de la aplicación y ORGANIZATION por el nombre con slug de la organización. Por ejemplo, https://github.com/organizations/octo-org/settings/apps/octo-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.