Sobre tokens de acesso de instalação
Para autenticar como uma instalação de aplicativo, você deve gerar um token de acesso de instalação. Para obter mais informações sobre como realizar a autenticação como uma instalação de aplicativo, confira "Autenticando como uma instalação de aplicativo GitHub".
Observação: em vez de gerar um token de acesso de instalação, você pode usar os SDKs Octokit de GitHub para realizar a autenticação como um aplicativo. O SDK cuidará da geração de um token de acesso de instalação para você e regenerará o token assim que ele expirar. Para obter mais informações sobre como realizar a autenticação como uma instalação de aplicativo, confira "Autenticando como uma instalação de aplicativo GitHub".
Mantenha o token de acesso de instalação seguro. Para obter mais informações, confira "Práticas recomendadas para criar um aplicativo do GitHub".
Como gerar um token de acesso de instalação
-
Gere um JWT (token Web JSON) para seu aplicativo. Para obter mais informações, confira "Como gerar um JWT (Token Web JSON) para um Aplicativo GitHub".
-
Obtenha o ID da instalação com a qual você deseja autenticar.
Se você estiver respondendo a um evento de webhook, a carga útil do webhook incluirá o ID de instalação.
Você também pode usar a API REST para localizar o ID de uma instalação do seu aplicativo. Você pode obter uma ID de instalação com os pontos de extremidade
GET /users/{username}/installation
,GET /repos/{owner}/{repo}/installation
,GET /orgs/{org}/installation
ouGET /app/installations
. Para obter mais informações, confira "Pontos de extremidade da API REST para o GitHub Apps".Você também pode encontrar a ID do aplicativo acessando a página de configurações dele. A ID do aplicativo é diferente da ID do cliente. Para saber como acessar a página de configurações do GitHub App, confira "Modificar um registro do Aplicativo GitHub".
-
Envie uma solicitação de
POST
da REST API para/app/installations/INSTALLATION_ID/access_tokens
. Inclua o token Web JSON no cabeçalhoAuthorization
da solicitação. SubstituaINSTALLATION_ID
pela ID de instalação com a qual você deseja autenticar.Por exemplo, envie esta solicitação de curl. Substitua
INSTALLATION_ID
pela ID da instalação eJWT
pelo token Web JSON:curl --request POST \ --url "http(s)://<em>HOSTNAME</em>/api/v3/app/installations/INSTALLATION_ID/access_tokens" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer JWT"
Opcionalmente, você pode usar os parâmetros de corpo
repositories
ourepository_ids
para especificar repositórios individuais que o token de acesso de instalação pode acessar. Se você não usarrepositories
ourepository_ids
para conceder acesso a repositórios específicos, o token de acesso de instalação poderá acessar todos os repositórios com permissão padrão da instalação. O token de acesso de instalação não pode receber acesso a repositórios que não receberam acesso da instalação. Você pode listar até 500 repositórios.Opcionalmente, use o corpo do parâmetro
permissions
para especificar as permissões que o token de acesso de instalação deve ter. Sepermissions
não for especificado, o token de acesso de instalação receberá todas as permissões que foram concedidas ao aplicativo. O token de acesso de instalação não pode receber permissões que o aplicativo não recebeu.Ao usar os parâmetros
permissions
para reduzir o acesso do token, a complexidade do token é aumentada devido ao número de permissões na solicitação e ao número de repositórios aos quais o token terá acesso. Se a complexidade for muito grande, você receberá uma mensagem de erro que indica o número máximo de repositórios que podem ser suportados. Nesse caso, você deve solicitar menos permissões com o parâmetropermissions
, use o parâmetrorepositories
ourepository_ids
para solicitar menos repositórios ou instalar o aplicativo em repositóriosall
em sua organização.A resposta incluirá um token de acesso à instalação, a hora em que o token expira, as permissões que o token possui e os repositórios que o token pode acessar. O token de acesso de instalação expirará após 1 hora.
Para obter mais informações sobre esse ponto de extremidade, confira "Pontos de extremidade da API REST para o GitHub Apps".
Observação: Na maioria dos casos, você pode usar
Authorization: Bearer
ouAuthorization: token
a fim de passar um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usarAuthorization: Bearer
.