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 "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

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

Se quiser usar a API REST do GitHub para uso pessoal, crie um personal access token. Se possível, o GitHub recomenda que você use um fine-grained personal access tokens em vez de um personal access token (classic). Para obter mais informações sobre como criar um personal access token, confira "Gerenciar seus tokens de acesso pessoal".

Se você estiver usando um fine-grained personal access token, seu fine-grained personal access token exigirá permissões específicas para acessar cada ponto de extremidade de API REST. O documento de referência da API REST para cada ponto de extremidade indica se o ponto de extremidade funciona com fine-grained personal access tokens, e declara quais permissões são necessárias para que o token 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 fine-grained personal access token pode ter acesso ao usar cada permissão, confira “Permissões necessárias para tokens de acesso pessoal refinados”.

Se você estiver usando um personal access token (classic), ele exigirá escopos específicos para acessar cada ponto de extremidade de API REST. Para obter orientação geral sobre quais escopos escolher, consulte "Escopos para aplicativos OAuth".

Personal access tokens e SSO do SAML

Se você usar um personal access token (classic) para acessar uma organização que impõe SSO (logon único) SAML para autenticação, será necessário autorizar seu token após a criação. Fine-grained personal access tokens são autorizados durante a criação do token, antes que o acesso à organização seja concedido. Para obter mais informações, confira "Autorizar o uso de um token de acesso pessoal para uso com logon único SAML".

Se você não autorizar o personal access token (classic) para o SSO do SAML antes de tentar usá-lo para acessar uma organização única que impõe o SSO do SAML, você poderá receber o erro 404 Not Found ou 403 Forbidden. Se você receber o erro 403 Forbidden, o cabeçalho X-GitHub-SSO incluirá uma URL que poderá ser usada para autorizar o token. A URL expira após uma hora.

Se você não autorizar o personal access token (classic) para o SSO do SAML antes de tentar usá-lo para acessar várias organizações, a API não retornará resultados das organizações que exigem SAML SSO e o cabeçalho X-GitHub-SSO indicará a ID das organizações que exigem autorização SAML SSO dos personal access token (classic). Por exemplo: X-GitHub-SSO: partial-results; organizations=21955855,20582480.

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.

Os tokens de acesso criados por aplicativos são automaticamente autorizados para o SSO do SAML.

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 "https://api.github.com/applications/YOUR_CLIENT_ID/token" \
--user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--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."

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

YAML

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/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 "https://api.github.com/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

Autenticação na API REST

Neste artigo