Skip to main content
ドキュメントへの更新が頻繁に発行されており、このページの翻訳はまだ行われている場合があります。 最新の情報については、「英語のドキュメント」を参照してください。

GitHub アプリのユーザー アクセス トークンの生成

アプリ アクティビティがユーザーに帰属することを示すために、GitHub App のユーザー アクセス トークンを生成できます。

ユーザー アクセス トークンについて

注: 有効期限が切れるユーザー アクセス トークンは現在オプションの機能であり、変更される可能性があります。 トークンの有効期限機能をオプトインまたはオプトアウトするには、「Activating optional features for GitHub Apps」をご覧ください。 詳細については、「GitHub App のユーザーからサーバーへのアクセストークンの期限切れ」を参照してください。

ユーザー アクセス トークンは、OAuth トークンの一種です。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンにスコープは使用されません。 代わりに、きめ細かいアクセス許可が使用されます。 ユーザー アクセス トークンを使用すると、ユーザーとアプリの両方が持っているアクセス許可のみが付与されます。 たとえば、アプリにリポジトリの内容を書き込むアクセス許可が付与されていても、ユーザーにできることが内容の読み取りだけである場合、ユーザー アクセス トークンではコンテンツの読み取りのみを行うことができます。

同様に、ユーザー アクセス トークンでアクセスできるのは、ユーザーとアプリの両方でアクセスできるリソースのみです。 たとえば、アプリにリポジトリ AB へのアクセス権が付与されていて、ユーザーがリポジトリ BC にアクセスできる場合、ユーザー アクセス トークンでリポジトリ B にはアクセスできますが、A または C にはアクセスできません。 REST API を使用して、ユーザー アクセス トークンでアクセスできるインストールとインストール内のリポジトリを確認できます。 詳しくは、「GitHub App インストール」の「GET /user/installations」と「GET /user/installations/{installation_id}/repositories」を参照してください。

ユーザー アクセス トークンを使用して API 要求を行う場合、ユーザー アクセス トークンのレート制限が適用されます。 詳しくは、「Rate limits for GitHub Apps (GitHub アプリのレート制限)」を参照してください。

既定では、ユーザー アクセス トークンは 8 時間後に期限切れになります。 更新トークンを使用してユーザー アクセス トークンを再生成できます。 詳しくは、「ユーザー アクセス トークンを更新する」を参照してください。

ユーザーは、GitHub App の認可を取り消すことができます。 詳しくは、「トークンの有効期限と取り消し」を参照してください。 ユーザーが GitHub App の認可を取り消すと、アプリは github_app_authorization Webhook を受け取ります。 GitHub Apps は、このイベントをサブスクライブ解除できません。 アプリがこの Webhook を受け取った場合は、トークンを取り消したユーザーに代わって行う API の呼び出しを停止する必要があります。 取り消されたアクセス トークンを使い続けると、アプリは 401 Bad Credentials エラーを受け取ることになります。 この Webhook について詳しくは、「Webhook のイベントとペイロード」を参照してください。

ユーザー アクセス トークンと更新トークンはセキュリティ保護する必要があります。 詳しくは、「Best practices for creating a GitHub App」を参照してください。

Web アプリケーション フローを使用してユーザー アクセス トークンを生成する

アプリがブラウザーで実行されている場合は、Web アプリケーション フローを使用してユーザー アクセス トークンを生成する必要があります。 Web アプリケーション フローの使用に関するチュートリアルについては、「Building a "Login with GitHub" button with a GitHub App」を参照してください。

  1. この URL にユーザーを誘導し、次のパラメーターの一覧から必要なクエリ パラメーターを追加します: http(s)://HOSTNAME/login/oauth/authorize。 たとえば、この URL では、client_id パラメーターと state パラメーターを指定します: http(s)://HOSTNAME/login/oauth/authorize?client_id=12345&state=abcdefg

    Query parameter (クエリ パラメーター)Type説明
    client_idstring必須。 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。

    ユーザー所有アプリの場合、設定ページは https://github.com/settings/apps/APP-SLUG です。

    組織所有アプリの場合、設定ページは https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG です。

    APP-SLUG をアプリのスラッグ化された名前に、ORGANIZATION を Organization のスラッグ化された名前に置き換えます。 たとえば、「 https://github.com/organizations/octo-org/settings/apps/octo-app 」のように入力します。
    redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。 これは、アプリの設定で "コールバック URL" として指定した URL のどれかと完全に一致している必要があり、追加のパラメーターを含めることはできません。
    statestring指定する場合、値には偽造攻撃から保護するランダムな文字列が含まれている必要があります。また、他の任意のデータを含めることもできます。
    loginstring指定すると、サインインとアプリの承認に使用できる特定のアカウントを持つユーザーに Web アプリケーション フローでプロンプトが表示されます。
    allow_signupbooleanOAuth フローの間に、認証されていないユーザーに対してGitHub へのサインアップの選択肢が提示されるかどうか。 既定値は、true です。 ポリシーでサインアップが禁止されている場合は、false を使用します。
  2. ユーザーが認可要求を受け入れた場合、ユーザーは GitHub でアプリ設定のコールバック URL のどれかにリダイレクトされ、次の手順でユーザー アクセス トークンを作成するために使用できる code クエリ パラメーターが提供されます。 前の手順で redirect_uri を指定した場合、そのコールバック URL が使用されます。 それ以外の場合は、アプリの設定ページの最初のコールバック URL が使用されます。

    前の手順で state パラメーターを指定した場合、GitHub にも state パラメーターが含まれます。 state パラメーターが前の手順で送信した state パラメーターと一致しない場合、要求を信頼できないため、Web アプリケーション フローを中止する必要があります。

  3. 以下のクエリ パラメータと共に、次の URL に POST 要求を行うことにより、前の手順の code をユーザー アクセス トークンに交換します: http(s)://HOSTNAME/login/oauth/access_token

    Query parameter (クエリ パラメーター)Type説明
    client_idstring必須。 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。

    ユーザー所有アプリの場合、設定ページは https://github.com/settings/apps/APP-SLUG です。

    組織所有アプリの場合、設定ページは https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG です。

    APP-SLUG をアプリのスラッグ化された名前に、ORGANIZATION を Organization のスラッグ化された名前に置き換えます。 たとえば、https://github.com/organizations/octo-org/settings/apps/octo-app のようにします。
    client_secretstring必須。 GitHub App のクライアント シークレット。 アプリの設定ページでクライアント シークレットを生成できます。
    codestring必須。 前の手順で受け取ったコード。
    redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。 これは、GitHub App を設定するときに "コールバック URL" として指定した URL のいずれかと完全に一致する必要があり、追加のパラメーターを含めることはできません。
    repository_idstringユーザー アクセス トークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。 ユーザー アクセス トークンのアクセスをさらに制限するには、このパラメーターを使います。
  4. GitHub から、次のパラメーターを含む応答が提供されます。

    応答パラメーター種類説明
    access_tokenstringユーザー アクセス トークン。 トークンは ghu_ で始まります。
    expires_inintegeraccess_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 28800 (8 時間) になります。
    refresh_tokenstring更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_ で始まります。
    refresh_token_expires_inintegerrefresh_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 15811200 (6 か月) になります。
    scopestringトークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。
    token_typestringトークンの種類。 値は常に bearer になります。
  5. 前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに API 要求を行います。 API 要求の Authorization ヘッダーにユーザー アクセス トークンを含めます。 次に例を示します。

    curl --request GET \
    --url "http(s)://HOSTNAME/api/v3/user" \
    --header "Accept: application/vnd.github+json" \
    --header "Authorization: Bearer USER_ACCESS_TOKEN"

デバイス フローを使用してユーザー アクセス トークンを生成する

注: デバイス フローはパブリック ベータ版であり、変更される可能性があります。

アプリがヘッドレスであるか、ブラウザーにアクセスできない場合は、デバイス フローを使用してユーザー アクセス トークンを生成する必要があります。 たとえば、CLI ツール、シンプルな Raspberry Pis、デスクトップ アプリケーションでは、デバイス フローを使う必要があります。 デバイス フローを使用するチュートリアルについては、「Building a CLI with a GitHub App」をご覧ください。

デバイス フローを使う前に、まずアプリの設定でこれを有効にする必要があります。 デバイス フローの有効化について詳しくは、「Modifying a GitHub App registration」を参照してください。

デバイス フローでは、OAuth 2.0 デバイス認可付与を使用します。

  1. POST 要求を client_id クエリ パラメーターと共に http(s)://HOSTNAME/login/device/code に送信します。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。

    • ユーザー所有アプリの場合、設定ページは https://github.com/settings/apps/APP-SLUG です。
    • 組織所有アプリの場合、設定ページは https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG です。

    APP-SLUG をアプリのスラッグ化された名前に、ORGANIZATION を Organization のスラッグ化された名前に置き換えます。 たとえば、「 https://github.com/organizations/octo-org/settings/apps/octo-app 」のように入力します。

  2. GitHub から、次のクエリ パラメーターを含む応答が提供されます。

    応答パラメーターType説明
    device_codestringデバイスの検証に使用される確認コード。 このコードの長さは 40 文字です。
    user_codestringユーザーがブラウザーでコードを入力できるように、アプリケーションで表示する必要がある確認コード。 このコードは8文字で、途中にハイフンがあります。 たとえば、「 WDJB-MJHT 」のように入力します。
    verification_uristringユーザーが自分の user_code を入力する必要がある URL。 URL は http(s)://HOSTNAME/login/device です。
    expires_inintegerdevice_codeuser_code の有効期限か切れるまでの秒数。 既定値は 900 秒 (15 分) です。
    intervalintegerデバイスの認可を完了するために新しいアクセス トークンのリクエスト (POST http(s)://HOSTNAME/login/oauth/access_token) を発行する前に経過する必要がある最小秒数。 この間隔が経過する前に要求を行うと、レート制限に達して slow_down エラーが返されます。 既定値は 5 秒です。
  3. 前の手順の user_codehttp(s)://HOSTNAME/login/device で入力するようにユーザーに求めます。

    expires_in の時間が経過する前にユーザーがコードを入力しないと、コードは無効になります。 そうなった場合は、デバイス フローを再起動する必要があります。

  4. デバイスおよびユーザー コードが期限切れになるか、ユーザーが user_code を入力してアプリが正常に承認されるまで、client_iddevice_codegrant_type のクエリ パラメーター (後述) と共に POST http(s)://HOSTNAME/login/oauth/access_token をポーリングします。

    Query parameter (クエリ パラメーター)Type説明
    client_idstring必須。 GitHub App のクライアント ID。
    device_codestring必須。 前の手順で受け取ったデバイス確認コード。
    grant_typestring必須。 付与タイプは urn:ietf:params:oauth:grant-type:device_code でなければなりません。
    repository_idstringユーザー アクセス トークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。 ユーザー アクセス トークンのアクセスをさらに制限するには、このパラメーターを使います。

    interval で示される頻度よりも高い頻度でこのエンドポイントをポーリングしないでください。 それを行うと、レート制限に達して slow_down エラーが返されます。 slow_down エラー応答によって、最後の interval に 5 秒が追加されます。

    ユーザーがコードを入力するまで、GitHub は 200 状態と error 応答クエリ パラメーターで応答します。

    エラー名説明
    authorization_pendingこのエラーコードは、認可リクエストが保留中で、ユーザがユーザコードをまだ入力していない場合に生じます。 アプリは、interval で指定された頻度を超えない頻度で POST http(s)://HOSTNAME/login/oauth/access_token をポーリングし続ける必要があります。
    slow_downslow_down エラーが返された場合、最小の interval、あるいは POST http(s)://HOSTNAME/login/oauth/access_token を使用するリクエスト間に必要な時間間隔に 5 秒が追加されます。 たとえば、開始時の間隔として要求間に最小で 5 秒が必要だった場合に、slow_down エラー応答が返された場合、トークンを求める新しい要求を行うまで少なくとも 10 秒待たなければならなくなります。 エラー応答には、使用する必要がある新しい interval 情報が含まれます。
    expired_tokenデバイス コードの有効期限が切れた場合は、token_expired エラーが表示されます。 デバイスコードを求める新しいリクエストを発行しなければなりません。
    unsupported_grant_typeOAuth トークン リクエストの POST http(s)://HOSTNAME/login/oauth/access_token でポーリングする際には、付与タイプを urn:ietf:params:oauth:grant-type:device_code として、入力パラメーターに含めなければなりません。
    incorrect_client_credentialsデバイスフローでは、アプリケーションのクライアントIDを渡さなければなりません。これは、アプリケーションの設定ページにあります。 クライアント ID が、アプリ ID およびクライアント シークレットと異なります。
    incorrect_device_code指定された device_code が無効です。
    access_denied認可プロセス中にユーザーがキャンセルをクリックした場合、access_denied エラーが返され、ユーザーは確認コードを再び利用することができなくなります。
    device_flow_disabledアプリケーションの設定で、デバイス フローが有効になっていません。 デバイス フローについて詳しくは、「Modifying a GitHub App registration」を参照してください。
  5. ユーザーが user_code を入力すると、GitHub から、次のクエリ パラメーターを含む応答があります。

    応答パラメーター種類説明
    access_tokenstringユーザー アクセス トークン。 トークンは ghu_ で始まります。
    expires_inintegeraccess_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 28800 (8 時間) になります。
    refresh_tokenstring更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_ で始まります。
    refresh_token_expires_inintegerrefresh_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 15811200 (6 か月) になります。
    scopestringトークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。
    token_typestringトークンの種類。 値は常に bearer になります。
  6. 前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに API 要求を行います。 API 要求の Authorization ヘッダーにユーザー アクセス トークンを含めます。 次に例を示します。

    curl --request GET \
    --url "http(s)://HOSTNAME/api/v3/user" \
    --header "Accept: application/vnd.github+json" \
    --header "Authorization: Bearer USER_ACCESS_TOKEN"

ユーザーがアプリをインストールするときにユーザー アクセス トークンを生成する

アプリ設定で [インストール時にユーザーの認可 (OAuth) を要求する] を選んだ場合、GitHub により、ユーザーがアプリをインストールした直後に Web アプリケーション フローが開始されます。

アプリがユーザー アカウントと Organization アカウントのどちらにインストールされるかに関係なく、この方法でユーザー アクセス トークンを生成できます。 ただし、アプリが Organization アカウントにインストールされた場合は、Web アプリケーション フローまたはデバイス フローを使用して、Organization 内の他のユーザーのユーザー アクセス トークンを生成する必要があります。

  1. ユーザーがアプリをインストールすると、GitHub でユーザーは http(s)://HOSTNAME/login/oauth/authorize?client_id=CLIENT_ID にリダイレクトされます。ここで、CLIENT_ID はアプリのクライアント ID です。

  2. ユーザーが認可要求を受け入れた場合、ユーザーは GitHub でアプリ設定の最初のコールバック URL にリダイレクトされ、code クエリ パラメーターが提供されます。

    どのコールバック URL を使用するかを制御する場合は、 [インストール時にユーザーの認可 (OAuth) を要求する] を選ばないでください。 代わりに、完全な Web アプリケーション フローでユーザーを誘導し、redirect_uri パラメーターを指定します。

  3. 以下のクエリ パラメータと共に、次の URL に POST 要求を行うことにより、前の手順の code をユーザー アクセス トークンに交換します: http(s)://HOSTNAME/login/oauth/access_token

    Query parameter (クエリ パラメーター)Type説明
    client_idstring必須。 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。

    ユーザー所有アプリの場合、設定ページは https://github.com/settings/apps/APP-SLUG です。

    組織所有アプリの場合、設定ページは https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG です。

    APP-SLUG をアプリのスラッグ化された名前に、ORGANIZATION を Organization のスラッグ化された名前に置き換えます。 たとえば、https://github.com/organizations/octo-org/settings/apps/octo-app のようにします。
    client_secretstring必須。 GitHub App のクライアント シークレット。 アプリの設定ページでクライアント シークレットを生成できます。
    codestring必須。 前の手順で受け取ったコード。
    redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。 これは、GitHub App を設定するときに "コールバック URL" として指定した URL のいずれかと完全に一致する必要があり、追加のパラメーターを含めることはできません。
    repository_idstringユーザー アクセス トークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。 ユーザー アクセス トークンのアクセスをさらに制限するには、このパラメーターを使います。
  4. GitHub から、次のパラメーターを含む応答が提供されます。

    応答パラメーター種類説明
    access_tokenstringユーザー アクセス トークン。 トークンは ghu_ で始まります。
    expires_inintegeraccess_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 28800 (8 時間) になります。
    refresh_tokenstring更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_ で始まります。
    refresh_token_expires_inintegerrefresh_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 15811200 (6 か月) になります。
    scopestringトークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。
    token_typestringトークンの種類。 値は常に bearer になります。
  5. 前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに API 要求を行います。 API 要求の Authorization ヘッダーにユーザー アクセス トークンを含めます。 次に例を示します。

    curl --request GET \
    --url "http(s)://HOSTNAME/api/v3/user" \
    --header "Accept: application/vnd.github+json" \
    --header "Authorization: Bearer USER_ACCESS_TOKEN"

更新トークンを使用してユーザー アクセス トークンを生成する

既定では、ユーザー アクセス トークンは 8 時間後に期限切れになります。 有効期限があるユーザー アクセス トークンを受け取った場合は、更新トークンも受け取ります。 更新トークンの有効期限は 6 か月後です。 この更新トークンを使用して、ユーザー アクセス トークンを再生成できます。 詳しくは、「ユーザー アクセス トークンを更新する」を参照してください。

GitHub では、有効期限があるユーザー アクセス トークンを使用することを強くお勧めします。 以前に有効期限があるユーザー アクセス トークンの使用をオプトアウトしたが、この機能を再び有効にする場合は、「Activating optional features for GitHub Apps」を参照してください。

ユーザー アクセス トークンでサポートされているエンドポイント

チェックラン

チェックスイート

行動規範

デプロイメントステータス

デプロイメント

イベント

フィード

Git Blob

Git コミット

Git参照

Gitタグ

Gitツリー

gitignoreテンプレート

インストール

Issueにアサインされた人

Issueコメント

Issueイベント

Issueのタイムライン

issue

ラベル

ライセンス

Markdown

Meta

マイルストーン

Organizationのフック

Organizationのメンバー

Organizationの外部コラボレータ

Organization pre-receive フック

OrganizationのTeamのプロジェクト

OrganizationのTeamリポジトリ

Organization Team

組織

プロジェクトのコラボレータ

プロジェクト

Pull Requestのコメント

Pull Requestのレビューイベント

Pull Requestのレビューのリクエスト

Pull Requestのレビュー

Pulls

リアクション

リポジトリ

リポジトリのアクティビティ

リポジトリのブランチ

リポジトリのコラボレータ

リポジトリのコミットコメント

リポジトリのコミット

リポジトリのコミュニティ

リポジトリのコンテンツ

リポジトリのイベントのディスパッチ

リポジトリのフック

リポジトリの招待

リポジトリのキー

リポジトリのPages

リポジトリ pre-receive フック

リポジトリのリリース

リポジトリ統計

Root

ステータス

Teamディスカッション

トピック

ユーザーの電子メール

ユーザのフォロワー

ユーザのGPGキー

ユーザの公開鍵

ユーザー