Frecuentemente publicamos actualizaciones de nuestra documentación. Es posible que la traducción de esta página esté en curso. Para conocer la información más actual, visita la documentación en inglés. Si existe un problema con las traducciones en esta página, por favor infórmanos.

Alcances para las Apps de OAuth

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

En este artículo

¿Te ayudó este documento?

Cuando estás configurando una App de OAuth en GitHub, los alcances solicitados se muestran al usuario en el formato de autorización.

Nota: Si estás creando una GitHub App, no necesitas proporcionar alcances en tu solicitud de autorización. Para obtener más información sobre esto, consulta la sección "Identificar y autorizar usuarios para las GitHub Apps".

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

$ curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/users/codertocat -I
HTTP/1.1 200 OK
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
  • X-OAuth-Scopes lista los alcances que tu token tiene autorizados.
  • X-Accepted-OAuth-Scopes lista los alcances que revisrá la acción.

Alcances disponibles

NombreDescripción
(no scope)Otorga acceso de solo lectura a la información pública (incluye la información del perfil de usuario público, y los gists)
site_adminOtorga a los administradores de sitio acceso a las Terminales de la API para la Administración de Servidor de GitHub Enterprise.
repoOtorga acceso completo a los repositorios públicos y privados. Esto incluye acceso de lectura/escritura al código, estados de las confirmaciones, proyectos de repositorio y de organización, invitaciones, colaboradores, agregar membrecías de equipo, estados de despliegue, y webhooks de repositorio para aquellos repositorios privados y públicos y para las organizaciones. También otorga la capacidad de administrar proyectos de usuario.
repo:statusOtorga acceso de lectura/escritura en los estados de confirmación de los repositorios privados. Este alcance solo se necesita para otorgar a otros usuarios o servicios el acceso a los estados de las confirmaciones en repositorios privados sin otorgarles acceso al código.
repo_deploymentOtorga acceso a los estados de despliegue para los repositorios públicos y privados. Este alcance solo se necesita para otorgar a otros usuarios o servicios el acceso a los estados de despliegue 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 se requiere para marcar a los repositorios públicos con una estrella.
repo:inviteOtorga capacidades de aceptar/rechazar las invitaciones para colaborar con un repositorio. Este alcance solo es necesario para otorgar a otros usuarios o servicios acceso a las invitaciones sin otorgar acceso al código.
admin:repo_hookOtorga acceso de lectura, escritura, ping y borrado a los ganchos de los repositorios privados y públicos. Los alcances repo y public_repo otorgan acceso completo a los repositorios, incluyendo a los ganchos de éstos. Utiliza el alcance admin:repo_hook para limitar el acceso únicamente a los ganchos de los repositorios.
write:repo_hookOtorga acceso de lectura, escritura y ping a los ganchos en los repositorios públicos o privados.
read:repo_hookOtorga acceso de lectura y de ping a los ganchos en los repositorios privados o públicos.
admin:orgPara administrar totalmente la organización y sus equipos, proyectos y membrecías.
write:orgAcceso de lectura y escritura para la membrecía de organización y de los equipos y para los proyectos de la organización.
read:orgAcceso de solo lectura para la membrecía de organización y de los equipos y para los proyectos de la organización.
admin:public_keyAdministrar totalmente las llaves públicas.
write:public_keyCrear, listar y ver los detalles de las llaves públicas.
read:public_keyListar y ver los detalles para las llaves públicas.
admin:org_hookOtorga acceso de lectura, escritura, ping y borrado para los ganchos de la organización. Nota: Los tokens de OAuth solo podrán realizar estas acciones en los ganchos de la organización los cuales haya creado la App de OAuth. Los tokens de acceso personal solo podrán llevar a cabo estas acciones en los ganchos de la organización que cree un usuario.
gistOtorga acceso de escritura a los gists.
notificacionesOtorga:
acceso de lectura a las notificaciones de un usuario
acceso de marcar como leído en los hilos
acceso de observar y dejar de observar en un repositorio, y
acceso de lectura, escritura y borrado para las suscripciones a los hilos.
usuarioOtorga acceso de lectura/escritura únicamente para la información de perfil. Este alcance incluye a user:email y user:follow.
read:userOtorga acceso para leer los datos de perfil de un usuario.
user:emailOtorga acceso de lectura para las direcciones de correo electrónico de un usuario.
user:followOtorga acceso para seguir o dejar de seguir a otros usuarios.
delete_repoOtorga acceso para borrar los repositorios administrables.
write:discussionPermite el acceso de lectura y escritura para los debates de equipo.
read:discussionPermite los accesos de lectura y escritura para los debates de equipo.
admin:gpg_keyAdministra las llaves GPG totalmente.
write:gpg_keyCrea, lista, y visualiza los detalles de las llaves GPG.
read:gpg_keyLista y visualiza los detalles de las llaves GPG.

Nota: Tu App de OAuth puede solicitar los alcances en la redirección inicial. Puedes especificar varios alcances si los separas con un espacio:

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

Alcances solicitados y otorgados

El atributo scope lista los alcances adjuntos 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 tu organización menos accesos de lo que solicitaste originalmente. También, los usuarios puede editar los alcances de los tokens después de completar un flujo de OAuth. Debes estar consciente de esta posibilidad y ajustar el comportamiento de tu aplicación de acuerdo con esto.

Es importante gestionar los casos de error en donde un usuario elige otorgarte menos acceso de lo que solicitaste originalmente. Por ejemplo, las aplicaciones pueden advertir o comunicar de cualquier otra forma a sus usuarios si experimentarán funcionalidad reducida o si serán incapaces de realizar alguna acción.

También, las aplicaciones siempre pueden enviar nuevamente de regreso a los usuarios a través del flujo para obtener permisos adicionales, pero no olvides que dichos usuarios siempre pueden rehusarse a hacerlo.

Revisa la sección Guía de aspectos básicos de la autenticación, la cual proporciona consejos sobre la gestión de alcances modificables de los tokens.

Alcances normalizados

Cuando solicites alcances múltiples, el token se guarda con una lista de alcances normalizada y descarta aquellos que se otro alcance solicitado incluya implícitamente. Por ejemplo, el solicitar user,gist,user:email dará como resultado un token con alcances de user y de gist únicamente, ya que el acceso que se otorga con el alcance user:email se incluye en el alcance user.

¿Te ayudó este documento?