Skip to main content

Ámbitos para las aplicaciones de OAuth

Los alcances te permiten especificar exactamente el tipo de acceso que necesitas. Los ámbitos limitan el acceso a los tokens de OAuth. No otorgan ningún permiso adicional más allá de aquél que el usuario ya tiene.

Nota: Considera la posibilidad de crear una GitHub App en lugar de una OAuth app. Las GitHub Apps usan permisos específicos en lugar de ámbitos, lo que te ofrece más control sobre lo que puede hacer la aplicación. Para obtener más información, vea «Diferencias entre aplicaciones de GitHub y aplicaciones de OAuth» y «Acerca de la creación de GitHub Apps».

Cuando configuras una OAuth app en GitHub, los ámbitos solicitados se muestran al usuario en el formulario de autorización.

Nota: Si va a compilar una aplicación de GitHub, no es necesario proporcionar alcances en la solicitud de autorización. Para más información al respecto, consulta "Autenticación con una aplicación de GitHub en nombre de un usuario".

Si tu OAuth app no tiene acceso a un buscador, tal como una herramienta de CLI, entonces no necesitarás especificar un alcance para que los usuarios se autentiquen dicha app. Para obtener más información, vea «Autorización de aplicaciones de OAuth».

Verifica los encabezados para ver qué alcances de OAuth tienes, y cuáles acepta la acción de la API:

$ curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
  • X-OAuth-Scopes enumera los alcances que el token ha autorizado.
  • X-Accepted-OAuth-Scopes enumera los alcances que comprueba la acción.

Ámbitos disponibles

NombreDescripción
(no scope)Concede acceso de solo lectura a la información pública (incluida la información del perfil de usuario, la información del repositorio y los gists)
repoConcede acceso completo a repositorios públicos, internos y privados, incluidos el acceso de lectura y escritura al código, los estados de confirmación, las invitaciones de repositorio, los colaboradores, los estados de implementación y los webhooks de repositorio. Nota: Además de los recursos relacionados con el repositorio, el ámbito repo también concede acceso para administrar recursos propiedad de la organización, incluidos proyectos, invitaciones, pertenencias a equipos y webhooks. Este ámbito también concede la capacidad de administrar proyectos propiedad de los usuarios.
repo:statusOtorga acceso de lectura/escritura a los estados de confirmación en los repositorios públicos y privados, privados e internos. Este alcance solo se necesita para otorgar acceso a otros usuarios o servicios a los estados de las confirmaciones en repositorios privados sin otorgarles acceso al código.
repo_deploymentConcede acceso a los estados de implementación para repositorios públicos y privados. Este alcance solo se necesita para otorgar acceso a otros usuarios o servicios a los estados de implementación, sin otorgarles acceso al código.
public_repoLimita el acceso a los repositorios públicos. Esto incluye el acceso de lectura/escritura al código, estados de las confirmaciones, proyectos de repositorio, colaboradores y estados de despliegue para los repositorios públicos y para las organizaciones. También es necesario para marcar con estrella los repositorios públicos.
repo:inviteConcede las capacidades de aceptación o rechazo de invitaciones para colaborar en un repositorio. Este alcance solo es necesario para otorgar acceso a otros usuarios o servicios a las invitaciones sin otorgar acceso al código.
security_eventsConcesiones:
acceso de lectura y escritura a eventos de seguridad en la API de code scanning
acceso de lectura y escritura a eventos de seguridad en la API de secret scanning
Este alcance solo se necesita para otorgar acceso a otros usuarios o servicios a los eventos de seguridad sin otorgarles acceso al código.
admin:repo_hookOtorga acceso de lectura, escritura, ping y eliminación a los enlaces en repositorios públicos, privados o internos. Los alcances repo y public_repo conceden acceso total a los repositorios, incluidos los enlaces de repositorio. Use el alcance admin:repo_hook para limitar el acceso solo a los enlaces de repositorio.
write:repo_hookOtorga acceso de lectura, escritura y ping a los enlaces en repositorios públicos, privados o internos.
read:repo_hookOtorga acceso de lectura y ping a los enlaces en repositorios públicos, privados o internos.
admin:orgPara administrar totalmente la organización y los equipos, proyectos y pertenencias.
write:orgAcceso de lectura y escritura a la pertenencia de la organización, los proyectos de la organización y la pertenencia a equipos.
read:orgAcceso de solo lectura a la pertenencia de la organización, los proyectos de la organización y la pertenencia a equipos.
admin:public_keyAdministre totalmente las claves públicas.
write:public_keyCree, enumere y vea los detalles de claves públicas.
read:public_keyEnumere y vea los detalles de claves públicas.
admin:org_hookOtorga acceso de lectura, escritura, ping y borrado a los enlaces de la organización. Nota: Los tokens de OAuth solo podrán realizar estas acciones en los enlaces de la organización que se hayan creado con la OAuth app. Un Personal access token solo podrá llevar a cabo estas acciones en los ganchos de la organización que cree un usuario.
gistOtorga acceso de escritura a los gists.
notificationsConcesiones:
acceso de lectura a las notificaciones de un usuario
acceso de marcación y lectura a subprocesos
acceso de inspección y anulación de inspección de un repositorio
acceso de lectura, escritura y eliminación a suscripciones de subprocesos
userOtorga acceso de lectura/escritura únicamente a la información de perfiles. Tenga en cuenta que este alcance incluye user:email y user:follow.
read:userOtorga acceso para leer los datos del perfil de un usuario.
user:emailOtorga acceso de lectura a las direcciones de correo electrónico de un usuario.
user:followOtorga acceso para seguir o no seguir a otros usuarios.
projectOtorga acceso de lectura y escritura a instancias de projects del usuario y la organización.
read:projectOtorga acceso de solo lectura a instancias de projects del usuario y la organización.
delete_repoOtorga acceso para eliminar repositorios que se pueden administrar.
write:packagesOtorga acceso para cargar o publicar un paquete en GitHub Packages. Para obtener más información, consulta "Publicación de un paquete".
read:packagesOtorga acceso para descargar o instalar paquetes desde GitHub Packages. Para obtener más información, consulta "Instalación de un paquete".
delete:packagesOtorga acceso para eliminar paquetes de GitHub Packages. Para obtener más información, vea «Borrar y restablecer un paquete».
admin:gpg_keyAdministración completa de claves de GPG.
write:gpg_keyCree, enumere y visualice los detalles de claves GPG.
read:gpg_keyEnumere y vea los detalles de las claves de GPG.
workflowConcede la capacidad de agregar y actualizar archivos de flujo de trabajo de GitHub Actions. Los archivos de flujo de trabajo pueden confirmarse sin este alcance en caso de que el mismo archivo (con la misma ruta y el mismo contenido) exista en otra rama en el mismo repositorio. Los archivos de flujo de trabajo pueden exponer GITHUB_TOKEN, que pueden tener un conjunto diferente de alcances. Para obtener más información, consulta "Autenticación automática de tokens".
admin:enterpriseProporciona control total de la funcionalidad empresarial. Para obtener más información, consulta "Administrar cuentas empresariales" en la documentación de la API de GraphQL.

Incluye manage_runners:enterprise, manage_billing:enterprise y read:enterprise.
manage_runners:enterpriseProporciona control total sobre los ejecutores autohospedados dentro de la empresa. Para obtener más información, vea «Acerca de los ejecutores autohospedados».
manage_billing:enterpriseLectura y escritura de datos de facturación de la empresa. Para obtener más información, vea «Puntos de conexión de la API de REST para la facturación».
read:enterpriseLectura de todos los datos de un perfil de empresa. No incluye los datos de perfil de los miembros de la empresa ni de las organizaciones.
read:audit_logLee los datos del registro de auditoría.

Nota: La OAuth app puede solicitar los ámbitos en el redireccionamiento inicial. Puede especificar varios alcances si los separa con un espacio utilizando %20:

https://github.com/login/oauth/authorize?
  client_id=...&
  scope=user%20repo_deployment

Alcances solicitados y otorgados

El atributo scope enumera los alcances vinculados al token que otorgó el usuario. Normalmente, estos alcances serán idénticos a lo que solicitaste. Sin embargo, los usuarios pueden editar sus alcances, lo cual es efectivo para otorgar a la organización menos accesos de los que se solicitó en un principio. Además, los usuarios pueden editar los alcances de los tokens después de completar un flujo de OAuth. Debe conocer esta posibilidad y ajustar el comportamiento de la aplicación en consecuencia.

Es importante gestionar los casos de error en donde un usuario elige otorgarle menos acceso del que solicitó en un principio. Por ejemplo, las aplicaciones pueden advertir o comunicar de cualquier otra forma a sus usuarios que se ha reducido el rendimiento o que no son capaces de realizar alguna acción.

Además, las aplicaciones siempre pueden redirigir a los usuarios a través del flujo para obtener permisos adicionales, pero no olvide que dichos usuarios siempre pueden negarse a hacerlo.

Consulte la Guía de aspectos básicos de la autenticación, que proporciona sugerencias sobre cómo controlar alcances de tokens modificables.

Alcances normalizados

Cuando se solicitan varios alcances, el token se guarda con una lista de alcances normalizada y se descartan aquellos que se incluyen de manera implícita en otro alcance solicitado. Por ejemplo, la solicitud user,gist,user:email dará como resultado un token con únicamente los alcances user y gist, porque el acceso concedido con el alcance user:email se incluye en el alcance user.