Autenticação na API REST

Sobre autenticação

Muitos pontos de extremidade da API REST exigirão autenticação ou retornam informações adicionais se você estiver autenticado. Além disso, você pode fazer mais solicitações por hora quando estiver autenticado.

Você pode autenticar sua solicitação enviando um token no cabeçalho Authorization da solicitação. No seguinte exemplo, substitua YOUR-TOKEN por uma referência ao token:

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"

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.

Se você tentar usar um ponto de extremidade da API REST sem um token ou com um token que não tenha permissões suficientes, receberá uma resposta 404 Not Found ou 403 Forbidden.

Autenticar com um personal access token

Caso você deseje usar a API REST do GitHub para uso pessoal, crie um personal access token. Para obter mais informações sobre como criar um personal access token, confira "Criando um token de acesso pessoal".

Autenticação com um token gerado por um aplicativo

Caso você deseje usar a API em nome de uma organização ou em nome de outro usuário, o GitHub recomenda que você use um GitHub App. Para obter mais informações, confira "About authentication with a GitHub App".

Você também pode criar um token OAuth com um OAuth App para acessar a API REST. No entanto, o GitHub recomenda que você use um GitHub App. Os GitHub Apps permitem mais controle sobre o acesso e a permissão que o aplicativo tem.

Usando a autenticação Básica

Alguns pontos de extremidade da API REST para os GitHub Apps e os OAuth Apps exigem que você use a autenticação básica para acessar o ponto de extremidade. Você usará a ID do cliente do aplicativo como o nome de usuário e o segredo do cliente do aplicativo como a senha.

Por exemplo:

curl --request POST \
--url "http(s)://HOSTNAME/api/v3/authorizations"
--user CLIENT_ID:CLIENT_SECRET

Encontre a ID do cliente e gere um segredo do cliente na página de configurações do aplicativo. Para os GitHub Apps de propriedade do usuário, a página de configurações é https://github.com/settings/apps/APP-SLUG. Para os GitHub Apps 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 slug do seu aplicativo e ORGANIZATION pela nome com slug da sua organização. Por exemplo, https://github.com/organizations/octo-org/settings/apps/octo-app.

Como se autenticar em um fluxo de trabalho de GitHub Actions

Se você quiser usar a API em um fluxo de trabalho de GitHub Actions, a GitHub recomenda que você se autentique com o GITHUB_TOKEN interno, em vez de criar um token. Você pode conceder permissões à GITHUB_TOKEN com a chave permissions. Para obter mais informações, confira "Autenticação automática de token".

Autenticação com um nome de usuário e uma senha

O GitHub recomenda que você use um token para se autenticar na API REST em vez da sua senha. Você tem mais controle sobre o que um token pode fazer e pode revogar um token a qualquer momento. No entanto, você também pode se autenticar na API REST usando seu nome de usuário e sua senha para autenticação básica. Para fazer isso, você transmitirá seu nome de usuário e a senha com a opção --user:

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/user"
--user USERNAME:PASSWORD