Skip to main content

Escopos para aplicativos OAuth

Os escopos permitem especificar exatamente que tipo de acesso você precisa. Os escopos limitam o acesso para tokens OAuth. Não concedem qualquer autorização adicional para além da que o usuário já possui.

Note

Considere a criação de um GitHub App em vez de um OAuth app. Os GitHub Apps usam permissões refinadas em vez de escopos, o que lhe dá mais controle sobre o que seu aplicativo pode fazer. Para saber mais, confira Diferenças entre os aplicativos GitHub e os aplicativos OAuth e Sobre a criação de Aplicativos do GitHub.

Ao configurar um aplicativo OAuth app no GitHub, os escopos solicitados são exibidos para o usuário no formulário de autorização.

Note

Se você estiver criando um Aplicativo GitHub, não precisará fornecer escopos na sua solicitação de autorização. Para obter mais informações sobre isso, confira Autenticação com um aplicativo GitHub em nome de um usuário.

Se seu OAuth app não tiver acesso a um navegador, como uma ferramenta de CLI, você não precisará especificar um escopo para que os usuários efetuem a autenticação no seu aplicativo. Para saber mais, confira Autorizar aplicativos OAuth.

Verifique os cabeçalhos para ver quais escopos do OAuth você tem e o que a ação da API aceita:

$ 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 lista os escopos autorizados pelo token.
  • X-Accepted-OAuth-Scopes lista os escopos verificados pela ação.

Escopos disponíveis

NomeDescrição
(no scope)Concede acesso somente leitura a informações públicas (incluindo informações de perfil de usuário, informações de repositório e gists)
repoConcede acesso total a repositórios públicos, internos e privados, incluindo acesso de leitura e gravação a código, status de confirmação, convites de repositório, colaboradores, status de implantação e webhooks de repositório. Observação: além dos recursos relacionados ao repositório, o escopo do repo também concede acesso para gerenciar recursos de propriedade da organização, incluindo projetos, convites, associações de equipe e webhooks. Esse escopo também concede a capacidade de gerenciar projetos pertencentes aos usuários.
repo:statusConcede acesso de leitura/gravação para fazer commit de status em público, privados e internos. Esse escopo só é necessário para permitir a outros usuários ou serviços acesso aos status de commit de repositórios privados sem permitir acesso ao código.
repo_deploymentConcede acesso a status de implantação para repositórios públicos e privados. Esse escopo só é necessário para conceder a outros usuários ou serviços acesso aos status de implantação, sem conceder acesso ao código.
public_repoLimita o acesso a repositórios públicos. Isso inclui acesso de leitura/gravação em código, status de commit, projetos de repositório, colaboradores e status de implantação de repositórios e organizações públicos. Também necessário para marcar repositórios públicos com estrela.
repo:inviteConcede habilidades de aceitação/recusa para convites para colaboração em um repositório. Esse escopo só é necessário para conceder a outros usuários ou serviços acesso a convites sem conceder acesso ao código.
security_eventsConcessões:
acesso de leitura e gravação a eventos de segurança na API de code scanning
acesso de leitura e gravação a eventos de segurança na API de secret scanning
Este escopo só é necessário para conceder a outros usuários ou serviços acesso a eventos de segurança sem conceder acesso ao código.
admin:repo_hookConcede acesso de leitura, gravação, ping e exclusão aos ganchos do repositório em repositórios públicos, privados ou internos. Os escopos repo e public_repo concedem acesso total aos repositórios, incluindo ganchos de repositório. Use o escopo admin:repo_hook para limitar o acesso apenas aos ganchos de repositório.
write:repo_hookConcede acesso de leitura, gravação e ping aos ganchos em repositórios públicos, privados ou internos.
read:repo_hookConcede acesso de leitura e ping aos ganchos em repositórios públicos, privados ou internosl.
admin:orgGerenciar totalmente a organização e suas equipes, projetos e associações.
write:orgAcesso de leitura e gravação a membros da organização e projetos da organização.
read:orgAcesso somente leitura a membros da organização, projetos da organização e membros da equipe.
admin:public_keyGerenciar totalmente as chaves públicas.
write:public_keyCriar, listar e exibir detalhes das chaves públicas.
read:public_keyListar e exibir detalhes das chaves públicas.
admin:org_hookConcede acesso de leitura, gravação, ping e exclusão aos ganchos da organização. Observação: os tokens OAuth só poderão executar essas ações nos ganchos da organização que foram criados pelo OAuth app. Os Personal access token só poderão realizar essas ações nos hooks da organização criados por um usuário.
gistConcede acesso de gravação a gists.
notificationsConcessões:
o acesso de leitura às notificações de um usuário
acesso de marcação como lido em threads
acesso de inspeção e cancelamento de inspeção em um repositório e
acesso de leitura, gravação e exclusão em assinaturas de thread.
userConcede acesso de leitura/gravação apenas às informações do perfil. Observe que esse escopo inclui user:email e user:follow.
read:userConcede acesso para ler os dados do perfil de um usuário.
user:emailConcede acesso de leitura aos endereços de email de um usuário.
user:followConcede acesso para seguir ou deixar de seguir outros usuários.
projectConcede acesso de leitura/gravação ao usuário e à organização projects.
read:projectConcede acesso somente leitura ao usuário e à organização projects.
delete_repoConcede acesso para excluir repositórios administráveis.
write:packagesConcede acesso para carregar ou publicar um pacote no GitHub Packages. Para saber mais, confira Publicando um pacote.
read:packagesConcede acesso para baixar ou instalar pacotes do GitHub Packages. Para saber mais, confira Instalando um pacote.
delete:packagesConcede acesso para excluir pacotes do GitHub Packages. Para saber mais, confira Excluir e restaurar um pacote.
admin:gpg_keyGerenciar totalmente as chaves GPG.
write:gpg_keyCriar, listar e exibir detalhes das chaves GPG.
read:gpg_keyListar e exibir detalhes detalhes das chaves GPG.
codespaceConcede a capacidade de criar e gerenciar codespaces. Os codespaces podem expor um GITHUB_TOKEN que pode ter um conjunto diferente de escopos. Para saber mais, confira Segurança no GitHub Codespaces.
workflowConcede a capacidade de adicionar e atualizar arquivos de fluxo de trabalho do GitHub Actions. Os arquivos do fluxo de trabalho podem ser confirmados sem este escopo se o mesmo arquivo (com o mesmo caminho e conteúdo) existir em outro branch no mesmo repositório. Os arquivos de fluxo de trabalho podem expor o GITHUB_TOKEN que pode ter um conjunto diferente de escopos. Para saber mais, confira Autenticação automática de token.
admin:enterpriseOferece controle total da funcionalidade empresarial. Para obter mais informações, confira Gerenciar contas corporativas na documentação da API do GraphQL.

Inclui manage_runners:enterprise, manage_billing:enterprise, e read:enterprise.
manage_runners:enterpriseOferece controle total sobre executores auto-hospedados na empresa. Para saber mais, confira Sobre executores auto-hospedados.
manage_billing:enterpriseLer e gravar dados de cobrança da empresa. Para saber mais, confira Pontos de extremidade da API REST para cobrança.
read:enterpriseLer todos os dados em um perfil empresarial. Não inclui dados de perfil de membros corporativos ou organizações.
read:audit_logLeia os dados do log de auditoria.

Note

Seu OAuth app pode solicitar os escopos no redirecionamento inicial. Você pode especificar vários escopos separando-os com um espaço usando %20:

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

Escopos solicitados e escopos concedidos

O atributo scope lista os escopos anexados ao token que foram concedido pelo usuário. Normalmente, estes escopos são idênticos aos que você solicitou. No entanto, os usuários podem editar os respectivos escopos, permitindo, efetivamente, ao seu aplicativo menos acesso do que você solicitou originalmente. Além disso, os usuários podem editar os escopos do token depois que o fluxo do OAuth for concluído. Você deve estar ciente dessa possibilidade e ajustar o comportamento do seu aplicativo de acordo.

É importante lidar com casos de erro em que um usuário opta por permitir menos acesso do que você solicitou originalmente. Por exemplo, os aplicativos podem alertar ou comunicar os usuários de que eles terão a funcionalidade reduzida ou não poderão realizar algumas ações.

Além disso, os aplicativos sempre podem enviar os usuários novamente por meio do fluxo para obter permissão adicional, mas não se esqueça de que os usuários sempre podem recusar isso.

Confira o guia Conceitos básicos sobre autenticação, que fornece dicas sobre como lidar com escopos de token modificáveis.

Escopos normalizados

Quando vários escopos são solicitados, o token é salvo com uma lista normalizada de escopos, descartando aqueles que estão implicitamente incluídos pelo escopo solicitado. Por exemplo, a solicitação de user,gist,user:email resultará em um token somente com os escopos user e gist, pois o acesso permitido com o escopo user:email está incluído no escopo user.