Observação: considere criar um GitHub App em vez de um OAuth App. Os GitHub App usam permissões refinadas em vez de escopos, o que lhe dá mais controle sobre o que seu aplicativo pode fazer. Para obter mais informações, confira "Diferenças entre Aplicativos do GitHub e Aplicativos OAuth" e "Sobre a criação de Aplicativos do GitHub."
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 "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 obter mais informações, confira "Autorizando 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
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) repo
Concede acesso completo a repositórios públicos 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 repositórios públicos e privados. 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 ou privados. 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 ou privados.
read:repo_hook
| Permite o acesso de leitura e ping aos ganchos em repositórios públicos ou privados.
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 Personal access token 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. project
| Permite acesso de leitura/gravação a projects de usuário e da organização (beta).
read:project
| Concede acesso somente leitura ao usuário e à organização projects. delete_repo
| Concede acesso para excluir repositórios administráveis. write:packages
| Permite o acesso para carregar ou publicar um pacote no GitHub Packages. Para obter mais informações, confira "Publicando um pacote".
read:packages
| Permite o acesso para baixar ou instalar pacotes do GitHub Packages. Para obter mais informações, confira "Instalando um pacote".
delete:packages
| Permite o acesso para excluir pacotes do GitHub Packages. Para obter mais informações, confira "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. codespace
| Permite a capacidade de criar e gerenciar codespaces. Os codespaces podem expor um GITHUB_TOKEN que pode ter um conjunto diferente de escopos. Para obter mais informações, confira "Segurança no GitHub Codespaces". workflow
| Permite 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 automática de token."
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
.