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.

Para autenticar sua solicitação, você precisará fornecer um token de autenticação com os escopos ou as permissões necessários. Existem algumas maneiras diferentes de obter um token: Você pode criar um personal access token, gerar um token com um GitHub App ou usar o GITHUB_TOKEN interno em um fluxo de trabalho do GitHub Actions.

Depois de criar um token, você pode autenticar sua solicitação enviando o token no cabeçalho Authorization de sua solicitação. Por exemplo, na solicitação a seguir, substitua YOUR-TOKEN por uma referência ao seu 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. A autenticação com credenciais inválidas retornará inicialmente uma resposta 401 Unauthorized.

Após detectar várias solicitações com credenciais inválidas em um curto período de tempo, a API rejeitará temporariamente todas as tentativas de autenticação para esse usuário (incluindo aquelas com credenciais válidas) com uma resposta 403 Forbidden. Para obter mais informações, confira "Limites de taxa para a API REST".

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 "Gerenciar seus tokens de acesso pessoal".

Seu personal access token requer escopos específicos para obter acesso a cada ponto de extremidade da API REST. Para obter orientação geral sobre quais escopos escolher, consulte "Escopos para aplicativos OAuth".

Personal access tokens e SSO do SAML

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 "Sobre a autenticação com um GitHub App".

A documentação de referência da API REST para cada ponto de extremidade indica se o ponto de extremidade funciona com GitHub Apps, e indica quais permissões são necessárias para que o aplicativo use o ponto de extremidade. Alguns pontos de extremidade podem exigir várias permissões e alguns pontos de extremidade podem exigir uma de várias permissões. Para obter uma visão geral de quais pontos de extremidade da API REST um GitHub App pode ter acesso ao usar cada permissão, confira “Permissões necessárias para os aplicativos GitHub”.

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/applications/YOUR_CLIENT_ID/token" \
--user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"
--data '{
  "access_token": "ACCESS_TOKEN_TO_CHECK"
}'

A ID do cliente e o segredo do cliente estão associados ao aplicativo, não ao proprietário do aplicativo ou a um usuário que autorizou o aplicativo. São usados para executar operações em nome do aplicativo, como a criação de tokens de acesso.

Se você for o proprietário de um GitHub App ou OAuth app ou se for um gerenciador de aplicativos para um GitHub App, poderá encontrar a ID do cliente e gerar um segredo do cliente na página de configurações de seu aplicativo. Para navegar até a página de configurações de seu aplicativo:

No canto superior direito de qualquer página do GitHub, clique na foto do seu perfil.
Acesse as configurações da sua conta.
- Para um aplicativo de propriedade de uma conta pessoal, clique em Configurações.
- Para um aplicativo de propriedade de uma organização:
  1. Clique em Suas organizações.
  2. À direita da organização, clique em Configurações.
Na barra lateral esquerda, clique em Configurações do desenvolvedor.
Na barra lateral esquerda, clique em GitHub Apps ou OAuth apps.
Para o GitHub Apps, à direita do GitHub App que você deseja acessar, clique em Editar. Para o OAuth apps, clique no aplicativo que você deseja acessar.
Ao lado de ID do Cliente, você verá a ID do cliente de seu aplicativo.
Ao lado de Segredos do cliente, clique em Gerar um novo segredo do cliente a fim de gerar um segredo do cliente para seu aplicativo.

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

Se isso não for possível, você poderá armazenar seu token como um segredo e usar o nome do seu segredo em seu fluxo de trabalho do GitHub Actions. Para obter mais informações sobre segredos, confira "Usar segredos em ações do GitHub".

Autenticação em um fluxo de trabalho GitHub Actions usando GitHub CLI

Para fazer uma solicitação autenticada para a API em um fluxo de trabalho do GitHub Actions usando o GitHub CLI, você pode armazenar o valor de GITHUB_TOKEN como uma variável de ambiente e usar a palavra-chave run para executar o subcomando GitHub CLI api. Para obter mais informações sobre a palavra-chave run, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

No fluxo de trabalho de exemplo a seguir, substitua PATH pelo caminho do ponto de extremidade. Para obter mais informações sobre o caminho, consulte "Introdução à API REST." Substitua HOSTNAME pelo nome de sua instância do GitHub Enterprise Server.

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api /PATH

Como se autenticar em um fluxo de trabalho de GitHub Actions usando `curl`

Para fazer uma solicitação autenticada para a API em um fluxo de trabalho do GitHub Actions usando o curl, você pode armazenar o valor de GITHUB_TOKEN como uma variável de ambiente e usar a palavra-chave run para executar uma solicitação curl para a API. Para obter mais informações sobre a palavra-chave run, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

No fluxo de trabalho de exemplo a seguir, substitua PATH pelo caminho do ponto de extremidade. Para obter mais informações sobre o caminho, consulte "Introdução à API REST." Substitua HOSTNAME pelo nome de sua instância do GitHub Enterprise Server.

YAML

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

Como se autenticar em um fluxo de trabalho de GitHub Actions usando JavaScript

Para obter um exemplo de como autenticar em um fluxo de trabalho do GitHub Actions usando JavaScript, consulte "Scripts com a API REST e o JavaScript".

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