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, deberás proporcionar un token de autenticación con los ámbitos o permisos necesarios. Hay varias maneras diferentes de obtener un token: puedes crear un personal access token, generar un token con un GitHub App, o usar el GITHUB_TOKEN integrado en un flujo de trabajo de GitHub Actions.

Después de crear un token, puedes autenticar la solicitud enviando un token en el encabezado Authorization de la solicitud. Por ejemplo, en la siguiente solicitud, 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. La autenticación con credenciales no válidas devolverá inicialmente una respuesta 401 Unauthorized.

Después de detectar varias solicitudes con credenciales no válidas en un breve periodo de tiempo, la API rechazará temporalmente todos los intentos de autenticación para el usuario en cuestión (incluidos aquellos con credenciales válidas) con una respuesta 403 Forbidden. Para más información, consulta Límites de volumen de la API de REST.

Autenticación con un personal access token

Si deseas usar la API de REST de GitHub para uso personal, puedes crear un personal access token. Si es posible, GitHub recomienda usar un fine-grained personal access token en lugar de un personal access token (classic). Para obtener más información sobre la creación de un 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. El documento de referencia de la API REST para cada punto de conexión indica si el punto de conexión funciona con fine-grained personal access token e indica qué permisos son necesarios para que el token use el punto de conexión. Algunos puntos de conexión pueden requerir varios permisos y algunos puntos de conexión pueden requerir uno de varios permisos. Para obtener información general sobre los puntos de conexión de la API REST a los que un fine-grained personal access token puede acceder con cada permiso, consulta Permisos necesarios para los tokens de acceso personal específicos.

Si usa un personal access token (classic), se requieren permisos específicos para acceder a cada punto de conexión de la API de REST. Para obtener instrucciones generales sobre qué ámbitos elegir, consulta Ámbitos para las aplicaciones de OAuth.

Personal access tokens actúan como tu identidad (limitada por los ámbitos o permisos seleccionados) al realizar solicitudes a la API de REST. Por lo tanto, es importante mantener seguros los personal access tokens. Para obtener más información sobre cómo proteger los personal access tokens, consulta Protección de las credenciales de API.

Personal access tokens e inicio de sesión único (SSO) de SAML

Si usa un personal access token (classic) para acceder a una organización que aplique el inicio de sesión único (SSO) de SAML para la autenticación, deberá autorizar el token después de la creación. Fine-grained personal access tokens se autorizan durante la creación de tokens, antes de conceder acceso a la organización. Para más información, consulta Autorización de un token de acceso personal para su uso con el inicio de sesión único.

Si no autoriza las instancias personal access token (classic) para el inicio de sesión único de SAML antes de intentar usarlo para acceder a una sola organización que aplique el inicio de sesión único de SAML, es posible que se genere el error 404 Not Found o 403 Forbidden. Si se produce el error 403 Forbidden, el encabezado X-GitHub-SSO incluirá una dirección URL que puede seguir para autorizar el token. La URL caduca después de una hora.

Si no autoriza los personal access token (classic) para el inicio de sesión único (SSO) de SAML antes de intentar usarlo para acceder a varias organizaciones, la API no devolverá resultados de las organizaciones que requieren el inicio de sesión único de SAML y el encabezado X-GitHub-SSO indicará el identificador de las organizaciones que requieren la autorización de SSO de SAML de los 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 más información, consulta Acerca de la autenticación con una aplicación de GitHub.

La documentación de referencia de la API de REST para cada punto de conexión indica si el punto de conexión funciona con GitHub Apps e indica qué permisos se requieren para que la aplicación use el punto de conexión. Algunos puntos de conexión pueden requerir varios permisos y algunos puntos de conexión pueden requerir uno de varios permisos. Para obtener información general sobre los puntos de conexión de la API REST a los que una GitHub Apps puede acceder con cada permiso, consulta 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:

En la esquina superior derecha de cualquier página en , 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:
  1. Haga clic en Sus organizaciones.
  2. 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 más información, consulta Uso de GITHUB_TOKEN en flujos de trabajo.

Si esto no es posible, se puede almacenar el token como un secreto y usar el nombre del secreto en el flujo de trabajo de GitHub Actions. Para obtener más información sobre secretos, consulta Using secrets in GitHub Actions.

Autenticación en un flujo de trabajo de GitHub CLI mediante GitHub Actions

Para realizar una solicitud autenticada a la API en un flujo de trabajo de GitHub Actions mediante GitHub CLI, puedes almacenar el valor de GITHUB_TOKEN como una variable de entorno y usar la palabra clave run para ejecutar el subcomando api de GitHub CLI. Para obtener más información sobre la palabra clave run, consulta Sintaxis del flujo de trabajo para GitHub Actions.

En el siguiente flujo de trabajo de ejemplo, reemplaza PATH por la ruta de acceso del punto de conexión. Para más información sobre la ruta de acceso, consulta Introducción a la API REST.

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api /PATH

Autenticación en un flujo de trabajo de GitHub Actions mediante `curl`

Para realizar una solicitud autenticada a la API en un flujo de trabajo de GitHub Actions mediante curl, se puede almacenar el valor de GITHUB_TOKEN como una variable de entorno y usar la palabra clave run para ejecutar una solicitud curl a la API. Para obtener más información sobre la palabra clave run, consulta Sintaxis del flujo de trabajo para GitHub Actions.

En el siguiente flujo de trabajo de ejemplo, reemplaza PATH por la ruta de acceso del punto de conexión. Para más información sobre la ruta de acceso, consulta Introducción a la API REST.

YAML

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

Autenticación en la API REST

En este artículo