REST API に対する認証

認証について

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

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

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

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

注: ほとんどの場合は、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 を作成できます。personal access token の作成について詳しくは、「個人用アクセストークンを管理する」を参照してください。

personal access token は、各 REST API エンドポイントにアクセスするために特定のスコープを必要とします。選択するスコープに関する全般的なガイダンスについては、「OAuth アプリのスコープ」を参照してください。

Personal access tokens と SAML SSO

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

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 を使うと、アプリのアクセスとアクセス許可をより詳細に制御できます。

基本認証を使用する

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

次に例を示します。

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

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

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

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

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 キーワードについて詳しくは、「ギットハブ　アクション　のワークフロー構文」をご覧ください。

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

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 キーワードについて詳しくは、「ギットハブ　アクション　のワークフロー構文」をご覧ください。

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

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

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

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

GitHub では、パスワードではなく、トークンを使用して REST API に対する認証を行うことが推奨されます。トークンで行うことができる内容をより詳細に制御でき、いつでもトークンを取り消すことができます。しかし、基本認証にユーザー名とパスワードを使用して REST API に対して認証することもできます。これを行うには、--user オプションを使用してユーザー名とパスワードを渡します。

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