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 "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".
Observação: Se um usuário relatar que não pode ver recursos pertencentes à organização depois de autorizar o GitHub App e a organização estiver usando o SSO do SAML, instrua-o a iniciar uma sessão SAML ativa para a organização antes de reautorizar. Para obter mais informações, confira "SAML e aplicativos GitHub" na documentação do GitHub Enterprise Cloud.
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".
-
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âmetrosclient_id
estate
: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
. Usefalse
quando uma política proibir inscrições. -
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ê especificouredirect_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âmetrostate
. Se o parâmetrostate
não corresponder ao parâmetrostate
que você enviou na etapa anterior, a solicitação não poderá ser confiável e o fluxo do aplicativo Web deverá ser anulado. -
Troque o
code
da etapa anterior por um token de acesso do usuário fazendo uma solicitaçãoPOST
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. -
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
. -
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
Observação: o fluxo de dispositivos está atualmente em beta 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".
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.
-
Envie uma solicitação
POST
parahttp(s)://HOSTNAME/login/device/code
com um parâmetro de consultaclient_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". -
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 ouser_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 erroslow_down
. O padrão é 5 segundos. -
Solicite que o usuário insira o
user_code
da etapa anterior nahttp(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. -
Sonde
POST http(s)://HOSTNAME/login/oauth/access_token
com os parâmetros de consultaclient_id
,device_code
egrant_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 ouser_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 erroslow_down
. A resposta de erroslow_down
adiciona cinco segundos ao últimointerval
.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 porinterval
.slow_down
Quando você recebe o erro slow_down
, cinco segundos extras são adicionados aointerval
ou ao período mínimo necessário entre as solicitações por meio dePOST 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 erroslow_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 novointerval
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 OAuthPOST 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". -
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
. -
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.
-
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 queCLIENT_ID
é a ID do cliente do aplicativo. -
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
. -
Troque o
code
da etapa anterior por um token de acesso do usuário fazendo uma solicitaçãoPOST
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. -
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
. -
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.