Quando o seu aplicativo GitHub age em nome de um usuário, ele realiza solicitações de usuário para servidor. Essas solicitações devem ser autorizadas com o token de acesso de um usuário. As solicitações de usuário para servidor incluem a solicitação de dados para um usuário, como determinar quais repositórios devem ser exibidos para um determinado usuário. Essas solicitações também incluem ações acionadas por um usuário, como executar uma criação.
Identificando usuários no seu site
Para autorizar usuários para aplicativos-padrão executados no navegador, use o fluxo de aplicativo web.
Fluxo do aplicativo web
Ao usar o fluxo de aplicativo web, o processo para identificar usuários no seu site é:
- Os usuários são redirecionados para solicitar sua identidade do GitHub
- Os usuários são redirecionados de volta para o seu site pelo GitHub
- Seu aplicativo GitHub acessa a API com o token de acesso do usuário
Se você selecionar Solicitar autorização de usuário (OAuth) durante a instalação ao criar ou modificar seu aplicativo, a etapa 1 será concluída durante a instalação do aplicativo. Para obter mais informações, consulte "Autorizando usuários durante a instalação".
1. Solicitar identidade do GitHub de um usuário
GET http(s)://[hostname]/login/oauth/authorize
Quando seu aplicativo GitHub especifica um parâmetro do login, ele solicita aos usuários com uma conta específica que podem usar para iniciar sessão e autorizar seu aplicativo.
Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
client_id | string | Obrigatório. O ID do cliente para o seu aplicativo GitHub. Você pode encontrá-lo em suas configurações do aplicativo GitHub quando você selecionar seu aplicativo. |
redirect_uri | string | A URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Este deve ser um match exato para a URL fornecida no campo de URL de callback de autorização do usuário ao configurar o aplicativo GitHub e não pode conter nenhum parâmetro adicional. |
estado | string | Isso deve conter uma string aleatória para proteger contra ataques falsificados e pode conter quaisquer outros dados arbitrários. |
login | string | Sugere uma conta específica para iniciar a sessão e autorizar o aplicativo. |
Observação: Você não precisa fornecer escopos na sua solicitação de autorização. Ao contrário do OAuth tradicional, o token de autorização é limitado às permissões associadas ao seu aplicativo GitHub e às do usuário.
2. Os usuários são redirecionados de volta para o seu site pelo GitHub
Se o usuário aceitar o seu pedido, O GitHub irá fazer o redirecionamento para seu site com um código temporário em um parâmetro de código, bem como o estado que você forneceu na etapa anterior em um parâmetro do estado. Se os estados não corresponderem, o pedido foi criado por terceiros e o processo deve ser abortado.
Observação: Se você selecionar Solicitar autorização de usuário (OAuth) durante a instalação ao criar ou modificar seu aplicativo, o GitHub irá retornar um código temporário que você precisará trocar por um token de acesso. O parâmetro estado não é retornado quando o GitHub inicia o fluxo OAuth durante a instalação do aplicativo.
Troque este código por um token de acesso.
POST http(s)://[hostname]/login/oauth/access_token
Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
client_id | string | Obrigatório. O ID do cliente para o seu aplicativo GitHub. |
client_secret | string | Obrigatório. O segredo do cliente do seu aplicativo GitHub. |
código | string | Obrigatório. O código que você recebeu como resposta ao Passo 1. |
redirect_uri | string | A URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Este deve ser um match exato para a URL fornecida no campo de URL de callback de autorização do usuário ao configurar o aplicativo GitHub e não pode conter nenhum parâmetro adicional. |
estado | string | A string aleatória inexplicável que você forneceu na etapa 1. |
Resposta
Por padrão, a resposta assume o seguinte formato:
access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer
3. Seu aplicativo GitHub acessa a API com o token de acesso do usuário
O token de acesso do usuário permite que o aplicativo GitHub faça solicitações para a API em nome de um usuário.
Autorização: token OUTH-TOKEN
GET http(s)://[hostname]/api/v3/user
Por exemplo, no cURL você pode definir o cabeçalho de autorização da seguinte forma:
curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/userVerifique quais recursos de instalação um usuário pode acessar
Observação: Para acessar a API com o seu aplicativo GitHub, você deve fornecer um tipo de mídia personalizado no cabeçalho Aceitar para as suas solicitações.
application/vnd.github.machine-man-preview+json
Aviso: A API pode mudar sem aviso prévio durante o período de pré-visualização. Os recursos de visualização não são compatíveis com o uso em produção. Em caso de problemas, entre em contato com your site administrator.
Depois de ter um token OAuth para um usuário, você pode verificar quais instalações o usuário poderá acessar.
Authorization: token OAUTH-TOKEN
GET /user/installations
Você também pode verificar quais repositórios são acessíveis a um usuário para uma instalação.
Authorization: token OAUTH-TOKEN
GET /user/installations/:installation_id/repositories
Você pode encontrar mais informações em: Listar instalações de aplicativos acessíveis para o token de acesso do usuário e Listar repositórios acessíveis para o token de acesso do usuário.
Tratar uma autorização revogada do aplicativo GitHub
Se um usuário revogar sua autorização de um aplicativo GitHub, o aplicativo receberá o webhook github_app_authorization por padrão. Os aplicativos GitHub não podem cancelar a assinatura deste evento. Qualquer pessoa pode revogar a autorização de um aplicativo GitHub a partir da sua página de configurações de conta do GitHub. Revogar a autorização de um aplicativo GitHub não desinstala o aplicativo GitHub. Você deve programar seu aplicativo do GitHub para que, ao receber esse webhook, ele para de chamar a API em nome da pessoa que revogou o token. Se o seu aplicativo GitHub continuar usando um token de acesso revogado, ele receberá a mensagem de erro 401 Bad Credentials.
Permissões no nível do usuário
Você pode adicionar permissões de nível de usuário ao seu aplicativo GitHub para acessar os recursos de usuários, como, por exemplo, e-mails de usuários, concedidos por usuários individuais como parte do fluxo de autorização do usuário . As permissões de nível de usuário diferem das permissões do repositório do nível de organização, que são concedidas no momento da instalação em uma conta de organização ou usuário.
Você pode selecionar permissões de nível de usuário nas configurações do seu aplicativo GitHub na seção Permissões de usuário na página Permissões & webhooks. Para obter mais informações sobre como selecionar permissões, consulte "Editando permissões de um aplicativo GitHub".
Quando um usuário instala seu aplicativo em sua conta, o prompt de instalação listará as permissões de nível de usuário que seu aplicativo solicita e explicará que o aplicativo pode pedir essas permissões a usuários individuais.
Como as permissões de nível de usuário são concedidas em uma base de usuário individual, você poderá adicioná-las ao aplicativo existente sem pedir que os usuários façam a atualização. No entanto, você precisa enviar usuários existentes através do fluxo de autorização do usuário para autorizar a nova permissão e obter um novo token de usuário para servidor para essas solicitações.
Solicitações de usuário para servidor
Embora a maior parte da interação da sua API deva ocorrer usando os tokens de acesso de servidor para servidor, certos pontos de extremidade permitem que você execute ações por meio da API usando um token de acesso do usuário. Seu aplicativo pode fazer as seguintes solicitações usando pontos de extremidade do GraphQL v4 ou REST v3.
Pontos de extremidade compatíveis
Execuções de verificação
- Criar uma verificação de execução
- Obter uma verificação de execução
- Atualizar uma execução de verificação
- Listar anotações de execução de verificação
- Listar execuções de verificações em um conjunto de verificações
- Listar execuções de verificação para uma referência do GIt
conjuntos de verificações
- Criar um conjunto de verificações
- Obter um conjunto de verificações
- Ressolicitar um conjunto de verificação
- Atualizar preferências do repositório para conjuntos de verificações
- Listar os conjuntos de verificação para uma referência do Git
Códigos de conduta
Status da implementação
Implantações
Eventos
Feeds
Blobs do Git
Commits do Git
Refs do Git
- Criar uma referência* Obter uma referência
- Lista de referências correspondentes
- Atualizar uma referência
- Excluir uma referência
Tags do Git
Árvores do Git
Modelos do Gitignore
Instalações
Responsáveis pelo problema
Comentários do problema
- Listar comentários do problema
- Criar um comentário do problema
- Listar comentários de problemas para um repositório
- Obter um comentário do issue
- Atualizar um comentário do problema
- Excluir comentário do problema
Eventos do problema
Linha do tempo do problema
Problemas
- Listar problemas atribuídos ao usuário autenticado
- Listar responsáveis
- Verificar se um usuário pode ser atribuído
- Listar problemas do repositório
- Cria um problema
- Obter um problema
- Atualizar um problema
- Bloquear um problema
- Desbloquear um problema
Etiquetas
- Listar etiquetas para um problema
- Adicionar etiquetas a um problema
- Definir etiquetas para um problema
- Remover todas as etiquetas de um problema
- Remover uma etiqueta de um problema
- Listar etiquetas para um repositório
- Criar uma etiqueta
- Obter uma etiqueta
- Atualizar uma etiqueta
- Excluir uma etiqueta
- Obter etiquetas para cada problema em um marco
Licenças
markdown
Meta
Marcos
Hooks da organização
- Listar webhooks da organização
- Criar um webhook da organização
- Obter um webhook da organização
- Atualizar um webhook da organização
- Excluir um webhook da organização
- Consultar um webhook da organização
Integrantes da organização
- Listar integrantes da organização
- Verificar associação da organização para um usuário
- Remover um membro da organização
- Obter a associação de uma organização para um usuário
- Definir associação de organização para um usuário
- Remover associação de organização para um usuário
- Listar membros públicos da organização
- Verificar a associação da organização pública para um usuário
- Definir associação à organização pública para o usuário autenticado
- Remover associação à organização pública para o usuário autenticado
Colaboradores externos da organização
- Listar colaboradores externos para uma organização
- Converter um integrante da organização em colaborador externo
- Remover colaboradores externos de uma organização
Hooks pre-receive da organização
- Listar hooks pre-receive para uma organização
- Obter um hook pre-receive para uma organização
- Atualizar a aplicação do hook pre-receive para uma organização
- Remover a aplicação do hook pre-receive para uma organização
Repositórios da equipe da organização
- Listar repositórios da equipe
- Verificar permissões da equipe para um repositório
- Adicionar ou atualizar as permissões do repositório da equipe
- Remover um repositório de uma equipe
Equipes da organização
Organizações
- Listar organizações
- Obter uma organização
- Atualizar uma organização
- Listar associações de organizações para os usuários autenticados
- Obter uma associação de organização para o usuário autenticado
- Atualizar uma associação de organização para o usuário autenticado
- Listar organizações para o usuário autenticado
- Listar organizações para um usuário
Colaboradores do projeto
- Listar colaboradores do projeto
- Adicionar colaborador do projeto
- Remover colaborador do projeto
- Obter permissão de projeto para um usuário
Projetos
- Listar projetos da organização
- Criar um projeto da organização
- Obter um projeto
- Atualizar um projeto
- Excluir um projeto
- Listar colunas do projeto
- Criar uma coluna do projeto
- Obter uma coluna do projeto
- Atualizar uma coluna do projeto
- Excluir uma coluna do projeto
- Listar cartões do projeto
- Criar um cartão de projeto
- Mover uma coluna do projeto
- Obter um cartão do projeto
- Atualizar um cartão do projeto
- Excluir um cartão do projeto
- Mover um cartão do projeto
- Listar projetos do repositório
- Criar um projeto do repositório
Commentários pull
- Listar comentários de revisão em um pull request
- Criar um comentário de revisão para um pull request
- Listar comentários de revisão em um repositório
- Obter um comentário de revisão para um pull request
- Atualizar um comentário de revisão para um pull request
- Excluir um comentário de revisão para um pull request
Eventos de revisão de pull request
Solicitações de revisão de pull request
- Listar revisores solicitados para um pull request
- Solicitar revisores para um pull request
- Remover revisores solicitados de um pull request
Revisões de pull request
- Listar comentários para um pull request
- Criar uma revisão para um pull request
- Obter uma revisão para um pull request
- Atualizar uma revisão para um pull request
- Listar comentários para uma revisão de pull request
Pulls
- Listar pull requests
- Criar um pull request
- Obter um pull request
- Atualizar um pull request
- Listar commits em um pull request
- Listar arquivos de pull requests
- Verifiarse um pull request foi mesclado
- Mesclar um pull request (Botão de mesclar)
Reações
- Excluir uma reação
- Listar reações para um comentário de commit
- Criar reação para um comentário de commit
- Listar reações para um problema
- Criar reação para um problema
- Listar reações para um comentário do problema
- Criar reação para um comentário do problema
- Listar reações para um comentário de revisão de pull request
- Criar reação para um comentário de revisão de pull request
- Listar reações para um comentário de discussão de equipe
- Criar reação para um comentário de discussão em equipe
- Listar reações para uma discussão de equipe
- Crie uma reação para discussão de equipe
Repositórios
- Listar repositórios da organização
- Criar um repositório para o usuário autenticado
- Obter um repositório
- Atualizar um repositório
- Excluir um repositório
- Comparar dois commits
- Listar contribuidores do repositório
- Listar bifurcações
- Criar uma bifurcação
- Listar idiomas do repositório
- Listar tags do repositório
- Listar equipes do repositório
- Transferir um repositório
- Listar repositórios públicos
- Listar repositórios para o usuário autenticado
- Listar repositórios para um usuário
- Criar repositório usando um modelo de repositório
Atividade do repositório
- Listar observadores
- Listar inspetores
- Listar repositórios favoritados pelo usuário
- Verificar se um repositório foi favoritado pelo usuário autenticado
- Favorite um repositório para o usuário autenticado
- Desmarque um repositório como favorito para o usuário autenticado
- Listar repositórios inspecionados por um usuário
Branches do repositório
- Listar branches
- Obter um branch
- Obter proteção do branch
- Atualizar proteção do branch
- Excluir proteção do branch
- Obter proteção do branch do administrador
- Definir proteção do branch de administrador
- Excluir proteção do branch de administrador
- Obter proteção de revisão do pull request
- Atualizar proteção de revisão do pull request
- Excluir proteção de revisão do pull request
- Obter proteção de assinatura do commit
- Criar proteção de assinatura do commit
- Excluir proteção de assinatura do commit
- Obter proteção contra verificações de status
- Atualizar proteção da verificação de status
- Remover proteção da verificação de status
- Obter todos os contextos de verificação de status
- Adicionar contextos de verificação de status
- Definir contextos de verificação de status
- Remover contextos de verificação de status
- Obter restrições de acesso
- Excluir restrições de acesso
- Listar equipes com acesso ao branch protegido
- Adicionar restrições de acesso da equipe
- Definir restrições de acesso da equipe
- Remover restrição de acesso da equipe
- Listar restrições de usuário do branch protegido
- Adicionar restrições de acesso do usuário
- Definir restrições de acesso do usuário
- Remover restrições de acesso do usuário
- Mesclar um branch
Colaboradores do repositório
- Listar colaboradores do repositório
- Verifique se um usuário é colaborador de um repositório
- Adicionar colaborador de repositório
- Remover um colaborador de repositório
- Obter permissões de repositório para um usuário
Comentários do commit do repositório
- Listar comentários de commit para um repositório
- Obter um comentário de commit
- Atualizar um comentário de commit
- Excluir um comentário de commit
- Listar comentários de commit
- Criar um comentário de commit
Commits do repositório
- Listar commits
- Obter um commit
- Listar branches para o commit principal
- Listar pull requests associados ao commit
Comunidade do repositório
Conteúdo do repositório
- Fazer o download de um arquivo do repositório
- Obter conteúdo de repositório
- Criar ou atualizar conteúdo do arquivo
- Excluir um arquivo
- Obter um LEIAME do repositório
- Obter a licença para um repositório
Hooks do repositório
- Listar webhooks de repositório
- Criar um webhook do repositório
- Obter um webhook do repositório
- Atualizar um webhook do repositório
- Excluir um webhook do repositório
- Fazer ping no webhook de um repositório
- Testar o webhook do repositório de push
Convites do repositório
- Listar convites para repositórios
- Atualizar um convite para um repositório
- Excluir um convite para um repositório
- Listar convites de repositório para o usuário autenticado
- Aceitar um convite de repositório
- Recusar um convite de repositório
Chaves de repositório
- Listar chaves de implantação
- Criar uma chave de implantação
- Obter uma chave de implantação
- Excluir uma chave de implantação
Páginas do repositório
- Obter um site do GitHub Pages
- Criar um site do GitHub Pages
- Atualizar informações sobre um site do GitHub Pages
- Excluir um site do GitHub Pages
- Listar criações do GitHub Pages
- Solicitar uma criação do GitHub Pages
- Obter uma criação do GitHub Pages
- Obter a última criação de páginas
Hooks pre-receive do repositório
- Listar hooks pre-receive para um repositório
- Obter um hook pre-receive para um repositório
- Atualizar a aplicação de um hook pre-receive para um repositório
- Remover a aplicação de um hook pre-receive para um repositório
Versões do repositório
- Listar versões
- Criar uma versão
- Obter uma versão
- Atualizar uma versão
- Excluir uma versão
- Listar ativos da versão
- Obter um ativo da versão
- Atualizar um ativo da versão
- Excluir um ativo da versão
- Obter a atualização mais recente
- Obter uma versão pelo nome da tag
Estatísticas do repositório
- Obter a atividade semanal do commit
- Obter o último ano da atividade de commit
- Obter toda a atividade do commit do contribuidor
- Obter a contagem semanal do commit
- Obter a contagem do commit por hora para cada dia
Raiz
Pesquisar
- Buscar código
- Pesquisar commits
- Pesquisar etiquetas
- Pesquisar repositórios
- Pesquisar tópicos
- Pesquisar usuários
Status
- Obter o status combinado para uma referência específica
- Listar status de commit para uma referência
- Criar um status de commit
Discussões de equipe
- Listar discussões
- Criar discussão
- Obter discussão
- Atualizar uma discussão
- Excluir uma discussão
- Listar comentários da discussão
- Criar um comentário da discussão
- Obter um comentário da discussão
- Atualizar um comentário da discussão
- Excluir um comentário da discussão
Tópicos
Emails do usuário
- Listar endereços de e-mail para o usuário autenticado
- Adicionar endereço(s) de e-mail
- Excluir endereço(s) de e-mail
- Listar endereços de e-mail públicos para o usuário autenticado
Seguidores do usuário
- Listar seguidores de um usuário
- Listar as pessoas que um usuário segue
- Verificar se uma pessoa é seguida pelo usuário autenticado
- Seguir um usuário
- Deixar de seguir um usuário
- Verificar se um usuário segue outro usuário
Chaves Gpg do usuário
- Listar chaves GPG para o usuário autenticado
- Criar uma chave GPG para o usuário autenticado
- Obter uma chave GPG para o usuário autenticado
- Excluir uma chave GPG para o usuário autenticado
- Listar chaves gpg para um usuário
Chaves públicas do usuário
- Listar chaves SSH públicas para o usuário autenticado
- Criar uma chave SSH pública para o usuário autenticado
- Obter uma chave SSH pública para o usuário autenticado
- Excluir uma chave SSH pública para o usuário autenticado
- Listar chaves públicas para um usuário