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

Sobre tokens de acesso do usuário

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 "Pontos de extremidade da API REST para instalações do GitHub App".

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 "Fazer 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: http(s)://HOSTNAME/login/oauth/authorize. Por exemplo, esta URL especifica os parâmetros client_id e state: http(s)://HOSTNAME/login/oauth/authorize?client_id=12345&state=abcdefg.

   Parâmetro de consulta	Tipo	Necessário?	Descrição
   client_id	string	Obrigató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. Para saber como acessar a página de configurações do GitHub App, confira "Modificar um registro do Aplicativo GitHub".
   redirect_uri	string	Altamente recomendado	A 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.
   state	string	Altamente recomendado	Quando especificado, o valor deve conter uma cadeia de caracteres aleatória para proteção contra ataques falsificados e pode conter outros dados arbitrários.
   login	string	Opcional	Quando especificado, o fluxo do aplicativo Web solicitará aos usuários uma conta específica que possam usar para entrar e autorizar seu aplicativo.
   allow_signup	boolean	Opcional	Indica 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: http(s)://HOSTNAME/login/oauth/access_token

   Parâmetro de consulta	Tipo	Descrição
   client_id	string	Necessá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. Para saber como acessar a página de configurações do GitHub App, confira "Modificar um registro do Aplicativo GitHub".
   client_secret	string	Necessário. O segredo do cliente para seu GitHub App. Você pode gerar um segredo do cliente na página de configurações do aplicativo.
   code	string	Necessário. O código que você recebeu na etapa anterior.
   redirect_uri	string	A 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.
   repository_id	string	A 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.

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

   Parâmetro de resposta	Type	Descrição
   access_token	string	O token de acesso do usuário. O token começa com ghu_.
   expires_in	integer	O 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_token	string	O 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_in	integer	O 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á 15897600 (seis meses).
   scope	string	Os 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_type	string	O 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 "http(s)://HOSTNAME/api/v3/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

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".

Antes de usar o fluxo do dispositivo, você deve primeiro habilitá-lo nas configurações do aplicativo. Para obter mais informações sobre como habilitar o fluxo do dispositivo, confira "Modificar um registro do 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 http(s)://HOSTNAME/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. Para saber como acessar a página de configurações do GitHub App, confira "Modificar um registro do Aplicativo GitHub".

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

   Parâmetro de resposta	Type	Descrição
   device_code	string	Um código de verificação usado para verificar o dispositivo. Esse código tem 40 caracteres.
   user_code	string	Um 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_uri	string	A URL em que os usuários precisam inserir o user_code. A URL é: http(s)://HOSTNAME/login/device.
   expires_in	integer	O número de segundos antes que o device_code e o user_code expirem. O padrão é 900 segundos (ou 15 minutos).
   interval	integer	O número mínimo de segundos que precisa transcorrer para que você possa fazer uma nova solicitação de token de acesso (POST http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 consulta	Tipo	Descrição
   client_id	string	Necessário. A ID do cliente do GitHub App.
   device_code	string	Necessário. O código de verificação do dispositivo que você recebeu na etapa anterior.
   grant_type	string	Necessário. O tipo de concessão precisa ser urn:ietf:params:oauth:grant-type:device_code.
   repository_id	string	A 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 erro	Descrição
   authorization_pending	Este 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 http(s)://HOSTNAME/login/oauth/access_token com uma frequência não mais rápida do que a frequência especificada por interval.
   slow_down	Quando 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 http(s)://HOSTNAME/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_token	Se 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_type	O 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 http(s)://HOSTNAME/login/oauth/access_token é sondada.
   incorrect_client_credentials	Para 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_code	O device_code fornecido não é válido.
   access_denied	Quando 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_disabled	O 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 registro do 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 resposta	Type	Descrição
   access_token	string	O token de acesso do usuário. O token começa com ghu_.
   expires_in	integer	O 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_token	string	O 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_in	integer	O 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á 15897600 (seis meses).
   scope	string	Os 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_type	string	O 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 "http(s)://HOSTNAME/api/v3/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 http(s)://HOSTNAME/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: http(s)://HOSTNAME/login/oauth/access_token

   Parâmetro de consulta	Tipo	Descrição
   client_id	string	Necessá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. Para saber como acessar a página de configurações do GitHub App, confira "Modificar um registro do Aplicativo GitHub".
   client_secret	string	Necessário. O segredo do cliente para seu GitHub App. Você pode gerar um segredo do cliente na página de configurações do aplicativo.
   code	string	Necessário. O código que você recebeu na etapa anterior.
   redirect_uri	string	A 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.
   repository_id	string	A 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.

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

   Parâmetro de resposta	Type	Descrição
   access_token	string	O token de acesso do usuário. O token começa com ghu_.
   expires_in	integer	O 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_token	string	O 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_in	integer	O 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á 15897600 (seis meses).
   scope	string	Os 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_type	string	O 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 "http(s)://HOSTNAME/api/v3/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 novamente, confira "Ativando recursos opcionais para aplicativos do GitHub".

Solução de problemas

As seções a seguir descrevem alguns erros que você pode receber ao gerar um token de acesso do usuário.

Credenciais do cliente incorretas

Se o client_id ou o client_secret especificado estiver incorreto, você receberá um erro incorrect_client_credentials.

Para resolver esse erro, use as credenciais corretas do GitHub App. Encontre a ID do cliente e o segredo do cliente na página de configurações do GitHub App. Para saber como acessar a página de configurações do GitHub App, confira "Modificar um registro do Aplicativo GitHub".

Erro no redirecionamento do URI

Se você especificar um redirect_uri que não corresponda a uma das URLs de retorno de chamada no registro do GitHub App, ocorrerá um erro redirect_uri_mismatch.

Para resolvê-lo, forneça um redirect_uri que corresponda a uma das URLs de retorno de chamada do registro do GitHub App ou omita esse parâmetro para usar a primeira URL de retorno de chamada listada no registro do GitHub App. Para obter mais informações, confira "Sobre a URL de retorno de chamada de autorização do usuário".

Código de verificação incorreto

Se você estiver usando o fluxo do dispositivo e o código de verificação (device_code) especificado estiver incorreto, expirado ou não corresponder ao valor recebido da solicitação inicial para http(s)://HOSTNAME/login/device/code, ocorrerá um erro bad_verification_code.

Para resolver esse erro, você deve iniciar o fluxo do dispositivo novamente para obter um novo código. Para obter mais informações, confira "Como usar o fluxo de dispositivo para gerar um token de acesso do usuário".

Token de atualização inválido

Se o token de atualização especificado for inválido ou estiver expirado, você receberá um erro bad_refresh_token.

Para resolver esse erro, você precisa reiniciar o fluxo de aplicativo Web ou o fluxo do dispositivo para obter um novo token de acesso do usuário e um token de atualização. Você só receberá um token de atualização se o GitHub App estiver configurado para aceitar a expiração de tokens de acesso do usuário. Para obter mais informações, confira "Atualizar tokens de acesso do usuário".

Tipo de concessão sem suporte

Quando você solicita um token de acesso de usuário por meio do fluxo do dispositivo, o parâmetro grant_type precisa ser urn:ietf:params:oauth:grant-type:device_code. Quando você atualiza um token de acesso do usuário usando um token de atualização, o parâmetro grant_type precisa ser refresh_token. Se você não usar o tipo de concessão correto, receberá um erro unsupported_grant_type.

Email de usuário não verificado

Se o usuário para o qual você está tentando gerar um token de acesso do usuário não tiver verificado o endereço de email principal com o GitHub, você receberá um erro unverified_user_email.

Para resolver esse erro, solicite ao usuário que verifique o endereço de email principal na conta do GitHub. Para obter mais informações, confira "Verificar endereço de e-mail" na documentação do GitHub Free.