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.

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

Observação: se você estiver criando um Aplicativo no GitHub, não precisará fornecer escopos na sua solicitação de autorização. Para obter mais informações sobre isso, confira "Como identificar e autorizar usuários para Aplicativos do GitHub".

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 obter mais informações, confira "Como 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" http(s)://[hostname]/api/v3/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

Nome   Descrição ----- -----------  (no scope)   Concede acesso somente leitura a informações públicas (incluindo informações de perfil do usuário, informações do repositório e gists) site_admin   Concede aos administradores do site acesso aos pontos de extremidade da API de Administração do GitHub Enterprise Server. repo   Concede acesso completo a repositórios públicos, internos e privados, incluindo acesso de leitura e gravação a códigos, status de commit, 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:status| Permite o 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_deployment| Permite o acesso aos status de implantação de repositórios públicos e privados. Esse escopo só é necessário para permitir a outros usuários ou serviços acesso aos status de implantação sem permitir acesso ao código.  public_repo| Limita o acesso aos 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 os repositórios públicos marcados com estrela.  repo:invite | Permite a capacidade de aceitação/recusa de convites para colaboração em um repositório. Esse escopo só é necessário para permitir a outros usuários ou serviços acesso a convites sem permitir acesso ao código.  security_events | Permite:
acesso de leitura e gravação a eventos de segurança na API de code scanning
Esse escopo só é necessário para permitir a outros usuários ou serviços acesso a eventos de segurança sem permitir acesso ao código. admin:repo_hook | Permite o acesso de leitura, gravação, ping e exclusão a ganchos de repositório em repositórios públicos, privados ou internos. Os escopos do repo e do public_repo permitem o acesso completo 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_hook | Permite o acesso de leitura, gravação e ping aos ganchos em repositórios públicos, privados ou internos.  read:repo_hook| Permite o acesso de leitura e ping aos ganchos em repositórios públicos, privados ou internos. admin:org | Gerencia por completo a organização e as respectivas equipes, projetos e associações.  write:org| Acesso de leitura e gravação à associação à organização, aos projetos da organização e à associação à equipe.  read:org| Acesso somente leitura à associação à organização, aos projetos da organização e à associação à equipe. admin:public_key | Gerenciar por completo as chaves públicas.  write:public_key| Criar, listar e ver detalhes das chaves públicas.  read:public_key| Listar e ver detalhes das chaves públicas. admin:org_hook | Permite o acesso de leitura, gravação, ping e exclusão de 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 Aplicativo OAuth. Os tokens de acesso pessoal só poderão realizar essas ações nos hooks da organização criados por um usuário. gist | Permite o acesso de gravação nos gists. notifications | Permite:
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. user | Permite o acesso de leitura/gravação apenas nas informações do perfil. Observe que esse escopo inclui user:email e user:follow.  read:user| Permite o acesso para ler as informações do perfil de um usuário.  user:email| Permite o acesso de leitura nos endereços de email de um usuário.  user:follow| Permite acesso para seguir ou deixar de seguir outros usuários. delete_repo | Permite acesso para excluir repositórios administráveis. write:discussion | Permite o acesso de leitura e gravação para discussões em equipe.  read:discussion | Permite o acesso de leitura para discussões em equipe. write:packages | Concede acesso ao para fazer o upload ou publicação de um pacote no GitHub Packages. Para obter mais informações, confira "Como publicar um pacote". read:packages | Permite o acesso para baixar ou instalar pacotes do GitHub Packages. Para obter mais informações, confira "Como instalar um pacote". delete:packages | Permite o acesso para excluir pacotes do GitHub Packages. Para obter mais informações, confira "Como excluir e restaurar um pacote". admin:gpg_key | Gerenciar completamente as chaves GPG.  write:gpg_key| Criar, listar e ver detalhes das chaves GPG.  read:gpg_key| Listar e ver detalhes das chaves GPG. workflow | Concede 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 obter informações, confira "Autenticação em um fluxo de trabalho." admin:enterprise | Fornece controle completo de funcionalidade corporativo. 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:enterprise | Fornece controle total sobre os corredores auto-hospedados dentro da empresa. Para obter mais informações, confira "Sobre os executores auto-hospedados".  manage_billing:enterprise | Leia e grave dados de cobrança corporativos. Para obter mais informações, confira "Cobrança" na documentação da API REST.  read:enterprise | Ler todos os dados em um perfil corporativo. Não inclui dados de perfil de membros corporativos ou organizações.

Observação: seu Aplicativo OAuth 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.