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
Nome | Descriçã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) |
repo | Concede 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:status | Concede 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 | Concede 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_repo | Limita 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:invite | Concede 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_events | Concessõ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_hook | Concede 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_hook | Concede acesso de leitura, gravação e ping aos ganchos em repositórios públicos, privados ou internos. |
read:repo_hook | Concede acesso de leitura e ping aos ganchos em repositórios públicos, privados ou internosl. |
admin:org | Gerenciar totalmente a organização e suas equipes, projetos e associações. |
write:org | Acesso de leitura e gravação a membros da organização e projetos da organização. |
read:org | Acesso somente leitura a membros da organização, projetos da organização e membros da equipe. |
admin:public_key | Gerenciar totalmente as chaves públicas. |
write:public_key | Criar, listar e exibir detalhes das chaves públicas. |
read:public_key | Listar e exibir detalhes das chaves públicas. |
admin:org_hook | Concede 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. |
gist | Concede acesso de gravação a gists. |
notifications | Concessõ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. |
user | Concede acesso de leitura/gravação apenas às informações do perfil. Observe que esse escopo inclui user:email e user:follow . |
read:user | Concede acesso para ler os dados do perfil de um usuário. |
user:email | Concede acesso de leitura aos endereços de email de um usuário. |
user:follow | Concede acesso para seguir ou deixar de seguir outros usuários. |
project | Concede acesso de leitura/gravação ao usuário e à organização projects. |
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 | Concede acesso para carregar ou publicar um pacote no GitHub Packages. Para saber mais, confira Publicando um pacote. |
read:packages | Concede acesso para baixar ou instalar pacotes do GitHub Packages. Para saber mais, confira Instalando um pacote. |
delete:packages | Concede acesso para excluir pacotes do GitHub Packages. Para saber mais, confira Excluir e restaurar um pacote. |
admin:gpg_key | Gerenciar totalmente as chaves GPG. |
write:gpg_key | Criar, listar e exibir detalhes das chaves GPG. |
read:gpg_key | Listar e exibir detalhes detalhes das chaves GPG. |
codespace | Concede 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. |
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 saber mais, confira Autenticação automática de token. |
admin:enterprise | Oferece 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:enterprise | Oferece controle total sobre executores auto-hospedados na empresa. Para saber mais, confira Sobre executores auto-hospedados. |
manage_billing:enterprise | Ler e gravar dados de cobrança da empresa. Para saber mais, confira Pontos de extremidade da API REST para cobrança. |
read:enterprise | Ler todos os dados em um perfil empresarial. Não inclui dados de perfil de membros corporativos ou organizações. |
read:audit_log | Leia 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
.