Skip to main content
Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais atualizadas, acesse a documentação em inglês.
All products
Aplicativos

Como gerar um token de acesso do usuário para um GitHub App

Neste artigo

Você pode gerar um token de acesso do usuário para o GitHub App a fim de atribuir a atividade do aplicativo a um usuário.

Sobre tokens de acesso do usuário

Nota: os tokens de acesso do usuário que expiram são, atualmente, um recurso opcional e estão sujeitos a alterações. Para aceitar ou recusar o recurso de vencimento de token, confira "Ativando recursos opcionais para aplicativos do GitHub". Para obter mais informações, confira "Como expirar tokens de acesso de usuário para servidor para Aplicativos do GitHub".

Um token de acesso do usuário é um tipo de token OAuth. Ao contrário de um token OAuth tradicional, o token de acesso do usuário não usa escopos. Em vez disso, ele usa permissões refinadas. Um token de acesso do usuário só tem permissões que o usuário e o aplicativo têm. Por exemplo, se o aplicativo recebeu permissão para gravar o conteúdo de um repositório, mas o usuário só pode ler o conteúdo, o token de acesso do usuário só pode ler o conteúdo.

Da mesma forma, um token de acesso do usuário só pode acessar recursos que o usuário e o aplicativo podem acessar. Por exemplo, se um aplicativo receber acesso ao repositório A e B, e o usuário puder acessar o repositório B e C, o token de acesso do usuário poderá acessar o repositório B, mas não A ou C. Use a API REST para verificar quais instalações e quais repositórios em uma instalação um token de acesso do usuário pode acessar. Para obter mais informações, confira GET /user/installations e GET /user/installations/{installation_id}/repositories em "Instalações do Aplicativo do GitHub".

Quando você faz solicitações de API com um token de acesso do usuário, os limites de taxa para os tokens de acesso do usuário se aplicam. Para obter mais informações, confira "Limites de taxa para aplicativos GitHub".

Por padrão, o token de acesso do usuário expira após oito horas. Use um token de atualização para regenerar um token de acesso do usuário. Para obter mais informações, confira "Atualizar tokens de acesso do usuário".

Os usuários podem revogar a autorização de um GitHub App. Para obter mais informações, confira "Vencimento e revogação de token". Se um usuário revogar a autorização de um GitHub App, o aplicativo receberá o webhook github_app_authorization. O GitHub Apps não pode cancelar a assinatura deste evento. Se o aplicativo receber esse webhook, você deverá parar de chamar a API em nome do usuário que revogou o token. Se o aplicativo continuar usando um token de acesso revogado, ele receberá o erro 401 Bad Credentials. Para obter mais informações sobre esse webhook, confira "Eventos e cargas de webhook".

Você deve manter seguros os tokens de acesso do usuário e os tokens de atualização. Para obter mais informações, confira "Práticas recomendadas para criar um aplicativo do GitHub".

Como usar o fluxo do aplicativo Web para gerar um token de acesso do usuário

Se o aplicativo for executado no navegador, você deverá usar o fluxo do aplicativo Web para gerar um token de acesso do usuário. Para ver um tutorial sobre como usar o fluxo de aplicativo Web, confira "Criando um botão "Logon com o GitHub" com um Aplicativo GitHub".

  1. Direcione o usuário para essa URL e adicione todos os parâmetros de consulta necessários da seguinte lista de parâmetros: https://github.com/login/oauth/authorize. Por exemplo, esta URL especifica os parâmetros client_id e state: https://github.com/login/oauth/authorize?client_id=12345&state=abcdefg.

    Parâmetro de consultaTipoDescrição
    client_idstringNecessário. A ID do cliente do GitHub App. A ID do cliente é diferente da ID do aplicativo. Encontre a ID do aplicativo na página de configurações do aplicativo.

    No caso de aplicativos de propriedade do usuário, a página de configurações é https://github.com/settings/apps/APP-SLUG.

    Para aplicativos de propriedade da organização, a página de configurações é https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.

    Substitua APP-SLUG pelo nome com campo de dados dinâmico do aplicativo e ORGANIZATION pelo nome com campo de dados dinâmico da organização. Por exemplo, https://github.com/organizations/octo-org/settings/apps/octo-app.
    redirect_uristringA URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Isso precisa ser uma correspondência exata com uma das URLs fornecidas como uma "URL de retorno de chamada" nas configurações do aplicativo e não pode conter parâmetros adicionais.
    statestringQuando especificado, o valor deve conter uma cadeia de caracteres aleatória para proteção contra ataques falsificados e pode conter outros dados arbitrários.
    loginstringQuando especificado, o fluxo do aplicativo Web solicitará aos usuários uma conta específica que possam usar para entrar e autorizar seu aplicativo.
    allow_signupbooleanIndica se os usuários não autenticados terão a opção de se inscrever no GitHub durante o fluxo do OAuth. O padrão é true. Use false quando uma política proibir inscrições.

  2. Se o usuário aceitar sua solicitação de autorização, o GitHub redirecionará o usuário para uma das URLs de retorno de chamada nas configurações de aplicativo e fornecerá um parâmetro de consulta code que você poderá usar na próxima etapa para criar um token de acesso do usuário. Se você especificou redirect_uri na etapa anterior, essa URL de retorno de chamada será usada. Caso contrário, a primeira URL de retorno de chamada na página de configurações do aplicativo será usada.

    Se você especificou o parâmetro state na etapa anterior, o GitHub também incluirá um parâmetro state. Se o parâmetro state não corresponder ao parâmetro state que você enviou na etapa anterior, a solicitação não poderá ser confiável e o fluxo do aplicativo Web deverá ser anulado.

  3. Troque o code da etapa anterior por um token de acesso do usuário fazendo uma solicitação POST para essa URL com os seguintes parâmetros de consulta: https://github.com/login/oauth/access_token

    Parâmetro de consultaTipoDescrição
    client_idstringNecessário. A ID do cliente do GitHub App. A ID do cliente é diferente da ID do aplicativo. Encontre a ID do aplicativo na página de configurações do aplicativo.

    No caso de aplicativos de propriedade do usuário, a página de configurações é https://github.com/settings/apps/APP-SLUG.

    Para aplicativos de propriedade da organização, a página de configurações é https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.

    Substitua APP-SLUG pelo nome com campo de dados dinâmico do aplicativo e ORGANIZATION pelo nome com campo de dados dinâmico da organização. Por exemplo, https://github.com/organizations/octo-org/settings/apps/octo-app.
    client_secretstringNecessário. O segredo do cliente para seu GitHub App. Você pode gerar um segredo do cliente na página de configurações do aplicativo.
    codestringNecessário. O código que você recebeu na etapa anterior.
    redirect_uristringA URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Ela deve ser uma correspondência exata de uma das URLs que você forneceu como uma "URL de retorno de chamada" ao configurar o GitHub App e não pode conter parâmetros adicionais.

  4. O GitHub dará uma resposta que inclui os seguintes parâmetros:

    Parâmetro de respostaTipoDescrição
    access_tokenstringO token de acesso do usuário. O token começa com ghu_.
    expires_inintegerO número de segundos até a expiração do access_token. Se você desabilitar a expiração de tokens de acesso do usuário, esse parâmetro será omitido. O valor sempre será 28800 (oito horas).
    refresh_tokenstringO token de atualização. Se você desabilitar a expiração de tokens de acesso do usuário, esse parâmetro será omitido. O token começa com ghr_.
    refresh_token_expires_inintegerO número de segundos até a expiração do refresh_token. Se você desabilitar a expiração de tokens de acesso do usuário, esse parâmetro será omitido. O valor sempre será 15811200 (seis meses).
    scopestringOs escopos que o token tem. Esse valor sempre será uma cadeia de caracteres vazia. Ao contrário de um token OAuth tradicional, o token de acesso do usuário é limitado às permissões que o seu aplicativo e o usuário têm.
    token_typestringO tipo de token. O valor sempre será bearer.

  5. Use o token de acesso do usuário da etapa anterior para fazer solicitações de API em nome do usuário. Inclua o token de acesso do usuário no cabeçalho Authorization de uma solicitação de API. Por exemplo:

    curl --request GET \
--url "https://api.github.com/user" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer USER_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

Como usar o fluxo do dispositivo para gerar um token de acesso do usuário

Observação: o fluxo do dispositivo está em versão beta pública e sujeito a alterações.

Se o aplicativo não tiver periféricos ou não tiver acesso a um navegador, use o fluxo do dispositivo para gerar um token de acesso do usuário. Por exemplo, as ferramentas da CLI, Raspberry Pis simples e os aplicativos da área de trabalho devem usar o fluxo do dispositivo. Para ver um tutorial que usa o fluxo do dispositivo, confira "Criando uma CLI com um Aplicativo GitHub".

Para usar o fluxo do dispositivo, primeiro você precisa habilitá-lo nas configurações do aplicativo. Para obter mais informações sobre como habilitar o fluxo do dispositivo, confira "Modificar um aplicativo GitHub".

O fluxo do dispositivo usa a Concessão de Autorização de Dispositivo do OAuth 2.0.

  1. Envie uma solicitação POST para https://github.com/login/device/code com um parâmetro de consulta client_id. A ID do cliente é diferente da ID do aplicativo. Encontre a ID do aplicativo na página de configurações do aplicativo.

    • No caso de aplicativos de propriedade do usuário, a página de configurações é https://github.com/settings/apps/APP-SLUG.
    • Para aplicativos de propriedade da organização, a página de configurações é https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.

    Substitua APP-SLUG pelo nome com campo de dados dinâmico do aplicativo e ORGANIZATION pelo nome com campo de dados dinâmico da organização. Por exemplo, https://github.com/organizations/octo-org/settings/apps/octo-app.

  2. O GitHub dará uma resposta que inclui os seguintes parâmetros de consulta:

    Parâmetro de respostaTipoDescrição
    device_codestringUm código de verificação usado para verificar o dispositivo. Esse código tem 40 caracteres.
    user_codestringUm código de verificação que o seu aplicativo deve exibir para que o usuário possa inserir o código em um navegador. Este código tem 8 caracteres com um hífen no meio. Por exemplo, WDJB-MJHT.
    verification_uristringA URL em que os usuários precisam inserir o user_code. A URL é: https://github.com/login/device.
    expires_inintegerO número de segundos antes que o device_code e o user_code expirem. O padrão é 900 segundos (ou 15 minutos).
    intervalintegerO número mínimo de segundos que precisa transcorrer para que você possa fazer uma nova solicitação de token de acesso (POST https://github.com/login/oauth/access_token) a fim de concluir a autorização do dispositivo. Se você fizer uma solicitação antes do intervalo transcorrer, atingirá o limite de taxa e receberá o erro slow_down. O padrão é 5 segundos.

  3. Solicite que o usuário insira o user_code da etapa anterior na https://github.com/login/device.

    Se o usuário não inserir o código antes da hora de expires_in transcorrer, o código será inválido. Nesse caso, você deve reiniciar o fluxo do dispositivo.

  4. Sonde POST https://github.com/login/oauth/access_token com os parâmetros de consulta client_id, device_code e grant_type (descritos abaixo) até que os códigos do dispositivo e do usuário expirem ou o usuário tenha autorizado o aplicativo com sucesso inserindo o user_code.

    Parâmetro de consultaTipoDescrição
    client_idstringNecessário. A ID do cliente do GitHub App.
    device_codestringNecessário. O código de verificação do dispositivo que você recebeu na etapa anterior.
    grant_typestringNecessário. O tipo de concessão precisa ser urn:ietf:params:oauth:grant-type:device_code.
    repository_idstringA ID de um único repositório que o token de acesso do usuário pode acessar. Se o GitHub App ou o usuário não puder acessar o repositório, isso será ignorado. Use esse parâmetro para restringir ainda mais o acesso do token de acesso do usuário.

    Não sonde esse ponto de extremidade com uma frequência mais alta do que a frequência indicada por interval. Se você fizer isso, atingirá o limite de taxa e receberá o erro slow_down. A resposta de erro slow_down adiciona cinco segundos ao último interval.

    Até que o usuário insira o código, GitHub responderá com 200 status e um parâmetro de consulta de resposta error.

    Nome do erroDescrição
    authorization_pendingEste erro ocorre quando a solicitação de autorização está pendente e o usuário ainda não inseriu o código do usuário. É esperado que o aplicativo continue sondando o POST https://github.com/login/oauth/access_token com uma frequência não mais rápida do que a frequência especificada por interval.
    slow_downQuando você recebe o erro slow_down, cinco segundos extras são adicionados ao interval ou ao período mínimo necessário entre as solicitações por meio de POST https://github.com/login/oauth/access_token. Por exemplo, se o intervalo inicial exigir, pelo menos, cinco segundos entre as solicitações e você receber a resposta de erro slow_down, você precisará aguardar, no mínimo, dez segundos antes de fazer uma nova solicitação para um token. A resposta de erro inclui o novo interval que você precisa usar.
    expired_tokenSe o código do dispositivo expirar, você verá o erro token_expired. Você deve fazer uma nova solicitação para um código de dispositivo.
    unsupported_grant_typeO tipo de concessão precisa ser urn:ietf:params:oauth:grant-type:device_code e precisa ser incluído como um parâmetro de entrada quando a solicitação de token OAuth POST https://github.com/login/oauth/access_token é sondada.
    incorrect_client_credentialsPara o fluxo do dispositivo, você deve passar o ID de cliente do aplicativo, que pode ser encontrado na página de configurações do aplicativo. A ID do cliente é diferente da ID do aplicativo e do segredo do cliente.
    incorrect_device_codeO device_code fornecido não é válido.
    access_deniedQuando um usuário clicar em Cancelar durante o processo de autorização, você receberá o erro access_denied e o usuário não poderá usar o código de verificação novamente.
    device_flow_disabledO fluxo do dispositivo não foi habilitado nas configurações do aplicativo. Para obter mais informações sobre como habilitar o fluxo do dispositivo, confira "Modificar um aplicativo GitHub".

  5. Depois que o usuário inserir o user_code, o GitHub terá uma resposta que inclui os seguintes parâmetros de consulta:

    Parâmetro de respostaTipoDescrição
    access_tokenstringO token de acesso do usuário. O token começa com ghu_.
    expires_inintegerO número de segundos até a expiração do access_token. Se você desabilitar a expiração de tokens de acesso do usuário, esse parâmetro será omitido. O valor sempre será 28800 (oito horas).
    refresh_tokenstringO token de atualização. Se você desabilitar a expiração de tokens de acesso do usuário, esse parâmetro será omitido. O token começa com ghr_.
    refresh_token_expires_inintegerO número de segundos até a expiração do refresh_token. Se você desabilitar a expiração de tokens de acesso do usuário, esse parâmetro será omitido. O valor sempre será 15811200 (seis meses).
    scopestringOs escopos que o token tem. Esse valor sempre será uma cadeia de caracteres vazia. Ao contrário de um token OAuth tradicional, o token de acesso do usuário é limitado às permissões que o seu aplicativo e o usuário têm.
    token_typestringO tipo de token. O valor sempre será bearer.

  6. Use o token de acesso do usuário da etapa anterior para fazer solicitações de API em nome do usuário. Inclua o token de acesso do usuário no cabeçalho Authorization de uma solicitação de API. Por exemplo:

    curl --request GET \
--url "https://api.github.com/user" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer USER_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

Como gerar um token de acesso do usuário quando um usuário instala seu aplicativo

Se você selecionar Solicitar autorização do usuário (OAuth) durante a instalação nas configurações do aplicativo, o GitHub iniciará o fluxo do aplicativo Web imediatamente depois que um usuário instalar seu aplicativo.

Você pode gerar um token de acesso do usuário com esse método, independentemente de o aplicativo estar instalado em uma conta de usuário ou em uma conta de organização. No entanto, se o aplicativo tiver sido instalado em uma conta de organização, você precisará usar o fluxo do aplicativo Web ou o fluxo do dispositivo para gerar um token de acesso do usuário para outros usuários da organização.

  1. Quando um usuário instalar seu aplicativo, o GitHub redirecionará o usuário para https://github.com/login/oauth/authorize?client_id=CLIENT_ID, em que CLIENT_ID é a ID do cliente do aplicativo.

  2. Se o usuário aceitar sua solicitação de autorização, o GitHub redirecionará o usuário para a primeira URL de retorno de chamada nas configurações do aplicativo e fornecerá um parâmetro de consulta code.

    Caso você deseje controlar a URL de retorno de chamada que é usada, não selecione Solicitar autorização do usuário (OAuth) durante a instalação. Em vez disso, direcione os usuários pelo fluxo completo do aplicativo Web e especifique o parâmetro redirect_uri.

  3. Troque o code da etapa anterior por um token de acesso do usuário fazendo uma solicitação POST para essa URL com os seguintes parâmetros de consulta: https://github.com/login/oauth/access_token

    Parâmetro de consultaTipoDescrição
    client_idstringNecessário. A ID do cliente do GitHub App. A ID do cliente é diferente da ID do aplicativo. Encontre a ID do aplicativo na página de configurações do aplicativo.

    No caso de aplicativos de propriedade do usuário, a página de configurações é https://github.com/settings/apps/APP-SLUG.

    Para aplicativos de propriedade da organização, a página de configurações é https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.

    Substitua APP-SLUG pelo nome com campo de dados dinâmico do aplicativo e ORGANIZATION pelo nome com campo de dados dinâmico da organização. Por exemplo, https://github.com/organizations/octo-org/settings/apps/octo-app.
    client_secretstringNecessário. O segredo do cliente para seu GitHub App. Você pode gerar um segredo do cliente na página de configurações do aplicativo.
    codestringNecessário. O código que você recebeu na etapa anterior.
    redirect_uristringA URL no seu aplicativo para o qual os usuários serão enviados após a autorização. Ela deve ser uma correspondência exata de uma das URLs que você forneceu como uma "URL de retorno de chamada" ao configurar o GitHub App e não pode conter parâmetros adicionais.

  4. O GitHub dará uma resposta que inclui os seguintes parâmetros:

    Parâmetro de respostaTipoDescrição
    access_tokenstringO token de acesso do usuário. O token começa com ghu_.
    expires_inintegerO número de segundos até a expiração do access_token. Se você desabilitar a expiração de tokens de acesso do usuário, esse parâmetro será omitido. O valor sempre será 28800 (oito horas).
    refresh_tokenstringO token de atualização. Se você desabilitar a expiração de tokens de acesso do usuário, esse parâmetro será omitido. O token começa com ghr_.
    refresh_token_expires_inintegerO número de segundos até a expiração do refresh_token. Se você desabilitar a expiração de tokens de acesso do usuário, esse parâmetro será omitido. O valor sempre será 15811200 (seis meses).
    scopestringOs escopos que o token tem. Esse valor sempre será uma cadeia de caracteres vazia. Ao contrário de um token OAuth tradicional, o token de acesso do usuário é limitado às permissões que o seu aplicativo e o usuário têm.
    token_typestringO tipo de token. O valor sempre será bearer.

  5. Use o token de acesso do usuário da etapa anterior para fazer solicitações de API em nome do usuário. Inclua o token de acesso do usuário no cabeçalho Authorization de uma solicitação de API. Por exemplo:

    curl --request GET \
--url "https://api.github.com/user" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer USER_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

Como usar um token de atualização para gerar um token de acesso do usuário

Por padrão, os tokens de acesso do usuário expiram após oito horas. Se você receber um token de acesso do usuário com uma expiração, também receberá um token de atualização. O token de atualização expira após seis meses. Use esse token de atualização para regenerar um token de acesso do usuário. Para obter mais informações, confira "Atualizar tokens de acesso do usuário".

O GitHub incentiva fortemente você a usar tokens de acesso do usuário que expiram. Se você já recusou o uso de tokens de acesso do usuário que expiram, mas deseja habilitar esse recurso de novo, confira "Ativando recursos opcionais para aplicativos do GitHub".

Pontos de extremidade com suporte para tokens de acesso do usuário

Executores de ações

Segredos de ações

Artifacts

Execuções de verificação

conjuntos de verificações

Códigos de conduta

Status da implementação

Implantações

Eventos

Feeds

Blobs do Git

Confirmações do Git

Refs do Git

Tags do Git

Árvores do Git

Modelos do Gitignore

Instalações

Limites de interação

Responsáveis pelo problema

Comentários do problema

Eventos do problema

Linha do tempo do problema

Problemas

Trabalhos

Rótulos

Licenças

Markdown

Meta

Marcos

Hooks da organização

Convites da organização

Integrantes da organização

Colaboradores externos da organização

Projetos da aquipe da organização

Repositórios da equipe da organização

Sincronizar equipe da organização

Equipes da organização

Organizações

Autorizações de credencial das organizações

Scim das organizações

Importação de fonte

Colaboradores do projeto

Projetos

Commentários pull

Eventos de revisão de pull request

Solicitações de revisão de pull request

Revisões de pull request

Pulls

Reações

Repositórios

Atividade do repositório

Correções de segurança automatizadas no repositório

Branches do repositório

Colaboradores do repositório

Comentários do commit do repositório

Commits do repositório

Comunidade do repositório

Conteúdo do repositório

Envio de eventos do repositório

Hooks do repositório

Convites do repositório

Chaves de repositório

Páginas do repositório

Versões do repositório

Estatísticas do repositório

Alertas de vulnerabilidade de repositório

Root

Status

Tópicos

Tráfego

Bloquear usuário

Emails do Usuário

Seguidores do usuário

Chaves Gpg do usuário

Chaves públicas do usuário

Usuários

Execuções do fluxo de trabalho

Fluxos de trabalho