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: puede crear un personal access token, generar un token con un GitHub App, o usar el integrado en un GITHUB_TOKEN flujo de trabajo 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: 2026-03-10"

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 tasa de la API REST.

Autenticación con personal access token

Si desea usar la GitHub API REST para su uso personal, puede crear un personal access token. Si es posible, GitHub recomienda que use un fine-grained personal access token en lugar de un personal access token (classic). Para obtener más información sobre cómo crear un personal access token, vea Administración de tokens de acceso personal.

Si utiliza un fine-grained personal access token, su fine-grained personal access token requiere permisos específicos para acceder a cada extremo de la API 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 tokens y 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 fine-grained personal access token de conexión de la API REST a los que puede acceder con cada permiso, consulte Permisos necesarios para los tokens de acceso personal específicos.

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

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

Personal access tokens y SAML SSO

Si usa un personal access token (classic) para acceder a una organización que exige el inicio de sesión único (SSO) mediante SAML para la autenticación, deberá autorizar su token después de crearlo. Fine-grained personal access tokens se autorizan durante la creación del token, antes de que se conceda 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 su personal access token (classic) para el inicio de sesión único con SAML antes de intentar utilizarlo para acceder a una organización concreta que exija el inicio de sesión único con SAML, puede que reciba un error 404 Not Found o 403 Forbidden. Si recibe un error de 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 su personal access token (classic) para el SSO de SAML antes de intentar usarlo para acceder a varias organizaciones, la API no devolverá resultados de las organizaciones que requieran SSO de SAML, y el encabezado X-GitHub-SSO indicará el identificador de las organizaciones que requieren la autorización de SSO de SAML de su 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 desea usar la API para una organización o en nombre de otro usuario, GitHub recomienda usar .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 REST para cada punto de conexión indica si el punto de conexión funciona con GitHub Apps y 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 GitHub App de conexión de la API REST a los que puede acceder con cada permiso, consulte Permisos necesarios para aplicaciones de GitHub.

También puede crear un token de OAuth con OAuth app para acceder a la API REST. Sin embargo, GitHub recomienda que use un GitHub App en su lugar. GitHub Apps permite un mayor control sobre el acceso y el permiso que tiene la aplicación.

Los tokens de acceso creados por aplicaciones quedan autorizados automáticamente para SAML SSO.

Uso de autenticación básica

Algunos puntos de conexión de la API REST para GitHub Apps y OAuth apps requieren que use 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: 2026-03-10" \
--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 gestor de aplicaciones de un GitHub App, puede encontrar el identificador de cliente y generar un secreto de cliente en la página de configuración de su aplicación. Para ir a la página de configuración de la aplicación:

En la esquina superior derecha de cualquier página de GitHub, haga clic en la imagen 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 de la izquierda, haz clic en Developer settings.
En la barra lateral izquierda, haga clic en GitHub Apps o OAuth apps.
Para GitHub Apps, a la derecha de GitHub App al que desea acceder, haga clic en Editar. En OAuth apps, haga clic en la aplicación a la que desea acceder.
Junto a Id. de cliente, verás el Id. de cliente de tu 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 GitHub Actions flujo de trabajo

Si desea usar la API en un GitHub Actions flujo de trabajo, GitHub recomienda autenticarse con la función integrada en GITHUB_TOKEN en vez de crear un token. Puedes conceder permisos a GITHUB_TOKEN con la clave permissions. Para más información, consulta Uso de GITHUB_TOKEN para la autenticación en flujos de trabajo.

Si esto no es posible, puede guardar su token como un secreto y usar el nombre de su secreto en su flujo de trabajo GitHub Actions. Para obtener más información sobre secretos, consulta Uso de secretos en Acciones de GitHub.

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

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

En el siguiente flujo de trabajo de ejemplo, reemplaza PATH por la ruta de acceso del punto de conexión. Para obtener más información sobre la ruta de acceso, consulte 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 GitHub Actions flujo de trabajo mediante `curl`

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

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"

En este artículo