Gerando um token de acesso de instalação para um aplicativo GitHub

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 autenticar como uma instalação de aplicativo, consulte Authenticating como uma instalação do aplicativo GitHub.

Mantenha o token de acesso de instalação seguro. Para saber mais, confira Práticas recomendadas para criar um aplicativo GitHub.

Como gerar um token de acesso de instalação

1. Gere um JWT (token Web JSON) para seu aplicativo. Para saber mais, confira Gerando um JWT (Token Web JSON) para um aplicativo GitHub.

2. 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. Por exemplo, 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 ou GET /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 Modificando um registro de aplicativo GitHub.

3. Envie uma solicitação de POST da REST API para /app/installations/INSTALLATION_ID/access_tokens. Inclua o token Web JSON no cabeçalho Authorization da solicitação. Substitua INSTALLATION_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 e JWT pelo token Web JSON:

   curl --request POST \
   --url "http(s)://HOSTNAME/api/v3/app/installations/INSTALLATION_ID/access_tokens" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer JWT" \
   --header "X-GitHub-Api-Version: 2022-11-28"
   

   Opcionalmente, você pode usar os parâmetros de corpo repositories ou repository_ids para especificar repositórios individuais que o token de acesso de instalação pode acessar. Se você não usar repositories ou repository_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. Se permissions 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âmetro permissions, use o parâmetro repositories ou repository_ids para solicitar menos repositórios ou instalar o aplicativo em repositórios all 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 tem e os repositórios que o token pode acessar, se aplicável. 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 ou Authorization: token a fim de passar um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usar Authorization: Bearer.