REST API に対する認証

REST API に対して認証を行って、より多くのエンドポイントにアクセスし、レート制限を高めることができます。

この記事の内容

認証について

多くの REST API エンドポイント操作では、認証が必要であるか、認証されている場合は追加情報が返されます。 さらに、認証されている場合は 1 時間あたりの要求を増やすことができます。

要求を認証するには、必要なスコープまたはアクセス許可を持つ認証トークンを提供する必要があります。 トークンを取得するには、いくつかの方法があります。personal access token を作成したり、GitHub App を使ってトークンを生成したり、GitHub Actions ワークフローに組み込まれているGITHUB_TOKEN を使用したりできます。

トークンを作成すると、要求の Authorization ヘッダーでトークンを送信することで要求を認証できます。 たとえば、次の要求では、YOUR-TOKEN をトークンへの参照に置き換えます。

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

Note

ほとんどの場合は、Authorization: Bearer または Authorization: token を使用してトークンを渡すことができます。 ただし、JSON Web トークン (JWT) を渡す場合は、Authorization: Bearer を使用する必要があります。

ログイン失敗の制限

トークンなしで、またはアクセス許可が不十分なトークンで REST API エンドポイントを使用しようとすると、404 Not Found または 403 Forbidden 応答を受け取ります。 無効な資格情報で認証すると、401 Unauthorized 応答が返されます。

無効な資格情報を含むリクエストを短期間に複数回検出すると、API は、403 Forbidden 応答で、そのユーザに対するすべての認証試行 (有効な資格情報による試行を含む) を一時的に拒否します。 詳しくは、「REST API のレート制限」を参照してください。

personal access token

で認証を行う

個人用に GitHub REST API を使用する場合は、personal access tokenを作成できます。 可能であれば、GitHub は、personal access token (classic) ではなく fine-grained personal access token を使うことをお勧めします。 personal access tokenの作成について詳しくは、「個人用アクセス トークンを管理する」をご覧ください。

fine-grained personal access token を使用している場合、各 REST API エンドポイントにアクセスするには、fine-grained personal access token に特定のアクセス許可が必要です。 各エンドポイントの REST API リファレンス ドキュメントでは、エンドポイントが fine-grained personal access token で動作するかどうかを示し、トークンがエンドポイントを使用するために何のアクセス許可が必要かを示します。 一部のエンドポイントでは複数のアクセス許可が必要な場合があり、一部のエンドポイントでは複数のアクセス許可のうちの 1 つが必要な場合があります。 各アクセス許可で fine-grained personal access token がアクセスできる REST API エンドポイントの概要については、「AUTOTITLE」を参照してください。

personal access token (classic) を使用している場合、各 REST API エンドポイントにアクセスするには、特定の範囲が必要です。 選択するスコープに関する全般的なガイダンスについては、「OAuth アプリのスコープ」を参照してください。

Personal access tokens と SAML SSO

認証に SAML シングル サインオン (SSO) を適用する組織にアクセスするために personal access token (classic) を使用する場合は、作成後にトークンを承認する必要があります。 Fine-grained personal access token は、組織へのアクセスが許可される前、トークンの作成時に承認されます。 詳しくは、「SAMLシングルサインオンで利用するために個人アクセストークンを認可する」を参照してください。

SAML SSO を適用する 1 つの組織へのアクセスに personal access token (classic) を使用する前に SAML SSO に対して承認しないと、404 Not Found または 403 Forbidden エラーが発生する可能性があります。 403 Forbidden エラーが発生した場合は、X-GitHub-SSO ヘッダーには、トークンを承認するための URL が含まれます。 URL は 1 時間後に期限切れになります。

複数の組織へのアクセスに personal access token (classic) を使用する前に SAML SSO に対して承認しないと、API は SAML SSO を必要とする組織からの結果を返しません。X-GitHub-SSO ヘッダーには、personal access token (classic) の SAML SSO 認可を必要とする組織の ID が示されます。 (例: X-GitHub-SSO: partial-results; organizations=21955855,20582480)。

アプリによって生成されたトークンを使用した認証

Organization で、または他のユーザーの代わりに API を使用する場合、GitHub では、GitHub App の使用が推奨されます。 詳しくは、「GitHub アプリでの認証について」を参照してください。

各エンドポイントの REST API リファレンス ドキュメントでは、エンドポイントが GitHub Apps で動作するかどうかを示し、アプリがエンドポイントを使用するために必要なアクセス許可を示しています。 一部のエンドポイントでは複数のアクセス許可が必要な場合があり、一部のエンドポイントでは複数のアクセス許可のうちの 1 つが必要な場合があります。 GitHub Apps が各アクセス許可でアクセスできる REST API エンドポイントの概要については、「GitHub Appに必要な権限」を参照してください。

また、OAuth app を使用して OAuth トークンを作成し、REST API にアクセスすることもできます。 しかし、GitHub では、代わりに GitHub App を使用することが推奨されます。 GitHub Apps を使うと、アプリのアクセスとアクセス許可をより詳細に制御できます。

アプリによって作成されたアクセス トークンは、SAML SSO に対して自動的に承認されます。

基本認証を使用する

GitHub Apps と OAuth apps の一部の REST API エンドポイントでは、基本認証を使ってエンドポイントにアクセスする必要があります。 ユーザー名としてアプリのクライアント ID を使用し、パスワードとしてアプリのクライアント シークレットを使用します。

次に例を示します。

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"
}'

クライアント ID とクライアント シークレットは、アプリの所有者またはアプリを承認したユーザーではなく、アプリに関連付けられます。 アクセス トークンの作成など、アプリに代わって操作を実行するために使用されます。

GitHub App または OAuth app のオーナーである場合、または GitHub App のアプリ管理者である場合は、クライアント ID を見つけて、アプリの設定ページでクライアント シークレットを生成できます。 アプリの設定ページに移動するには:

  1. GitHub の任意のページの右上隅にある、自分のプロファイル写真をクリックします。
  2. アカウント設定にアクセスしてください。
    • 個人用アカウントが所有するアプリの場合は、[設定] をクリックします。
    • 組織が所有するアプリの場合:
      1. [自分の組織] をクリックします。
      2. 組織の右側にある [設定] をクリックします。
  3. 左側のサイドバーで [ 開発者設定] をクリックします。
  4. 左側のサイド バーで、[GitHub Apps] または [OAuth apps] をクリックします。
  5. GitHub Apps の場合、アクセスする GitHub App の右側にある [編集] をクリックします。 OAuth apps の場合は、アクセスするアプリをクリックします。
  6. [クライアント ID] の横に、アプリのクライアント ID が表示されます。
  7. [クライアント シークレット] の横にある [新しいクライアント シークレットの生成] をクリックして、アプリのクライアント シークレットを生成します。

GitHub Actions ワークフローにおける認証

GitHub Actions ワークフローで API を使用する場合、GitHub では、トークンを作成するのではなく、組み込み GITHUB_TOKEN で認証することが推奨されます。 permissions キーを使用して、GITHUB_TOKEN へのアクセス許可を付与できます。 詳しくは、「自動トークン認証」を参照してください。

これが不可能な場合は、トークンをシークレットとして格納し、GitHub Actions ワークフローでシークレットの名前を使用できます。 シークレットについて詳しくは、「GitHub Actions でのシークレットの使用」をご覧ください。

GitHub CLI を使用したGitHub Actions での認証

GitHub CLI を使用して GitHub Actions ワークフローで API に対して認証済み要求を行うには、環境変数として値 GITHUB_TOKEN を格納し、run キーワード (keyword)を使用して GitHub CLI api サブコマンドを実行します。 run キーワードについて詳しくは、「GitHub Actions　のワークフロー構文」をご覧ください。

次のワークフロー例では、PATH をエンドポイントのパスに置き換えます。 パスの詳細については、「REST API を使用した作業の開始」を参照してください。

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

curl を使用した GitHub Actions ワークフローにおける認証

curl を使用して GitHub Actions ワークフローで API に対して認証済み要求を行うには、環境変数として値 GITHUB_TOKEN を格納し、run キーワード (keyword)を使用して API に curl 要求を実行します。 run キーワードについて詳しくは、「GitHub Actions　のワークフロー構文」をご覧ください。

次のワークフロー例では、PATH をエンドポイントのパスに置き換えます。 パスの詳細については、「REST API を使用した作業の開始」を参照してください。

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"

JavaScript を使用した GitHub Actions ワークフローにおける認証

JavaScript を使用して GitHub Actions ワークフローで認証する方法の例については、「REST API と JavaScript を使用したスクリプト」を参照してください。

ユーザー名とパスワードによる認証

ユーザー名とパスワードによる認証はサポートされていません。 ユーザー名とパスワードを使用して認証しようとすると、4xx エラーが表示されます。

参考資料