ユーザー アクセス トークンについて
注: 有効期限が切れるユーザー アクセス トークンは現在オプションの機能であり、変更される可能性があります。 トークンの有効期限機能をオプトインまたはオプトアウトするには、「GitHub アプリのオプション機能のアクティブ化」をご覧ください。 詳細については、「GitHub App のユーザーからサーバーへのアクセストークンの期限切れ」を参照してください。
ユーザー アクセス トークンは、OAuth トークンの一種です。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンにスコープは使用されません。 代わりに、きめ細かいアクセス許可が使用されます。 ユーザー アクセス トークンを使用すると、ユーザーとアプリの両方が持っているアクセス許可のみが付与されます。 たとえば、アプリにリポジトリの内容を書き込むアクセス許可が付与されていても、ユーザーにできることが内容の読み取りだけである場合、ユーザー アクセス トークンではコンテンツの読み取りのみを行うことができます。
同様に、ユーザー アクセス トークンでアクセスできるのは、ユーザーとアプリの両方でアクセスできるリソースのみです。 たとえば、アプリにリポジトリ A
と B
へのアクセス権が付与されていて、ユーザーがリポジトリ B
と C
にアクセスできる場合、ユーザー アクセス トークンでリポジトリ B
にはアクセスできますが、A
または C
にはアクセスできません。 REST API を使用して、ユーザー アクセス トークンでアクセスできるインストールとインストール内のリポジトリを確認できます。 詳しくは、「GitHub Appインストール用 REST API エンドポイント」の「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 のイベントとペイロード」を参照してください。
ユーザー アクセス トークンと更新トークンはセキュリティ保護する必要があります。 詳しくは、「GitHub App を作成するためのベスト プラクティス」を参照してください。
注: GitHub App を承認した後に自分の Organization で所有しているリソースを表示できないことがユーザーから報告され、その Organization で SAML SSO を使用している場合、再認証する前に、Organization のアクティブな SAML セッションを開始するようにユーザーに指示します。 詳しい情報については、GitHub Enterprise Cloud ドキュメントの「SAML と GitHub Apps」を参照してください。
Web アプリケーション フローを使用してユーザー アクセス トークンを生成する
アプリがブラウザーで実行されている場合は、Web アプリケーション フローを使用してユーザー アクセス トークンを生成する必要があります。 Web アプリケーション フローの使用に関するチュートリアルについては、「GitHub App を使って [Login with GitHub] ボタンを作成する」を参照してください。
-
この 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_id
string
必須 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページに移動する方法について詳しくは、「GitHub App 登録の変更」を参照してください。 redirect_uri
string
強く推奨 認可の後にユーザが送られるアプリケーション中のURL。 これは、アプリの設定で "コールバック URL" として指定した URL のどれかと完全に一致している必要があり、追加のパラメーターを含めることはできません。 state
string
強く推奨 指定する場合、値には偽造攻撃から保護するランダムな文字列が含まれている必要があります。また、他の任意のデータを含めることもできます。 login
string
省略可能 指定すると、サインインとアプリの承認に使用できる特定のアカウントを持つユーザーに Web アプリケーション フローでプロンプトが表示されます。 allow_signup
boolean
省略可能 OAuth フローの間に、認証されていないユーザーに対してGitHub へのサインアップの選択肢が提示されるかどうか。 既定値は、 true
です。 ポリシーでサインアップが禁止されている場合は、false
を使用します。 -
ユーザーが認可要求を受け入れた場合、ユーザーは GitHub でアプリ設定のコールバック URL のどれかにリダイレクトされ、次の手順でユーザー アクセス トークンを作成するために使用できる
code
クエリ パラメーターが提供されます。 前の手順でredirect_uri
を指定した場合、そのコールバック URL が使用されます。 それ以外の場合は、アプリの設定ページの最初のコールバック URL が使用されます。前の手順で
state
パラメーターを指定した場合、GitHub にもstate
パラメーターが含まれます。state
パラメーターが前の手順で送信したstate
パラメーターと一致しない場合、要求を信頼できないため、Web アプリケーション フローを中止する必要があります。 -
以下のクエリ パラメータと共に、次の URL に
POST
要求を行うことにより、前の手順のcode
をユーザー アクセス トークンに交換します:http(s)://HOSTNAME/login/oauth/access_token
Query parameter (クエリ パラメーター) Type 説明 client_id
string
必須。 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページに移動する方法について詳しくは、「GitHub App 登録の変更」を参照してください。 client_secret
string
必須。 GitHub App のクライアント シークレット。 アプリの設定ページでクライアント シークレットを生成できます。 code
string
必須。 前の手順で受け取ったコード。 redirect_uri
string
認可の後にユーザが送られるアプリケーション中のURL。 これは、GitHub App を設定するときに "コールバック URL" として指定した URL のいずれかと完全に一致する必要があり、追加のパラメーターを含めることはできません。 repository_id
string
ユーザー アクセス トークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。 ユーザー アクセス トークンのアクセスをさらに制限するには、このパラメーターを使います。 -
GitHub から、次のパラメーターを含む応答が提供されます。
応答パラメーター Type 説明 access_token
string
ユーザー アクセス トークン。 トークンは ghu_
で始まります。expires_in
integer
access_token
の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に28800
(8 時間) になります。refresh_token
string
更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_
で始まります。refresh_token_expires_in
integer
refresh_token
の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に15897600
(6 か月) になります。scope
string
トークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。 token_type
string
トークンの種類。 値は常に bearer
になります。 -
前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに 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" \ --header "X-GitHub-Api-Version: 2022-11-28"
デバイス フローを使用してユーザー アクセス トークンを生成する
注: このデバイスは ベータ にあり、変更される可能性があります。
アプリがヘッドレスであるか、ブラウザーにアクセスできない場合は、デバイス フローを使用してユーザー アクセス トークンを生成する必要があります。 たとえば、CLI ツール、シンプルな Raspberry Pis、デスクトップ アプリケーションでは、デバイス フローを使う必要があります。 デバイス フローを使用するチュートリアルについては、「GitHub アプリを使用して CLI を構築する」をご覧ください。
デバイス フローを使用するには、まずアプリの設定でデバイス フローを有効にする必要があります。 デバイス フローの有効化について詳しくは、「GitHub App 登録の変更」を参照してください。
デバイス フローでは、OAuth 2.0 デバイス認可付与を使用します。
-
POST
要求をclient_id
クエリ パラメーターと共にhttp(s)://HOSTNAME/login/device/code
に送信します。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページにアクセスする方法について詳しくは、「GitHub App 登録の変更」を参照してください。 -
GitHub から、次のクエリ パラメーターを含む応答が提供されます。
応答パラメーター Type 説明 device_code
string
デバイスの検証に使用される確認コード。 このコードの長さは 40 文字です。 user_code
string
ユーザーがブラウザーでコードを入力できるように、アプリケーションで表示する必要がある確認コード。 このコードは8文字で、途中にハイフンがあります。 たとえば、「 WDJB-MJHT
」のように入力します。verification_uri
string
ユーザーが自分の user_code
を入力する必要がある URL。 URL はhttp(s)://HOSTNAME/login/device
です。expires_in
integer
device_code
とuser_code
の有効期限か切れるまでの秒数。 既定値は 900 秒 (15 分) です。interval
integer
デバイスの認可を完了するために新しいアクセス トークンのリクエスト ( POST http(s)://HOSTNAME/login/oauth/access_token
) を発行する前に経過する必要がある最小秒数。 この間隔が経過する前に要求を行うと、レート制限に達してslow_down
エラーが返されます。 既定値は 5 秒です。 -
前の手順の
user_code
をhttp(s)://HOSTNAME/login/device
で入力するようにユーザーに求めます。expires_in
の時間が経過する前にユーザーがコードを入力しないと、コードは無効になります。 そうなった場合は、デバイス フローを再起動する必要があります。 -
デバイスおよびユーザー コードが期限切れになるか、ユーザーが
user_code
を入力してアプリが正常に承認されるまで、client_id
、device_code
、grant_type
のクエリ パラメーター (後述) と共にPOST http(s)://HOSTNAME/login/oauth/access_token
をポーリングします。Query parameter (クエリ パラメーター) Type 説明 client_id
string
必須。 GitHub App のクライアント ID。 device_code
string
必須。 前の手順で受け取ったデバイス確認コード。 grant_type
string
必須。 付与タイプは urn:ietf:params:oauth:grant-type:device_code
でなければなりません。repository_id
string
ユーザー アクセス トークンでアクセスできる 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_down
slow_down
エラーが返された場合、最小のinterval
、あるいはPOST http(s)://HOSTNAME/login/oauth/access_token
を使用するリクエスト間に必要な時間間隔に 5 秒が追加されます。 たとえば、開始時の間隔として要求間に最小で 5 秒が必要だった場合に、slow_down
エラー応答が返された場合、トークンを求める新しい要求を行うまで少なくとも 10 秒待たなければならなくなります。 エラー応答には、使用する必要がある新しいinterval
情報が含まれます。expired_token
デバイス コードの有効期限が切れた場合は、 token_expired
エラーが表示されます。 デバイスコードを求める新しいリクエストを発行しなければなりません。unsupported_grant_type
OAuth トークン リクエストの 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
アプリケーションの設定で、デバイス フローが有効になっていません。 デバイス フローの有効化について詳しくは、「GitHub App 登録の変更」を参照してください。 -
ユーザーが
user_code
を入力すると、GitHub から、次のクエリ パラメーターを含む応答があります。応答パラメーター Type 説明 access_token
string
ユーザー アクセス トークン。 トークンは ghu_
で始まります。expires_in
integer
access_token
の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に28800
(8 時間) になります。refresh_token
string
更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_
で始まります。refresh_token_expires_in
integer
refresh_token
の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に15897600
(6 か月) になります。scope
string
トークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。 token_type
string
トークンの種類。 値は常に bearer
になります。 -
前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに 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" \ --header "X-GitHub-Api-Version: 2022-11-28"
ユーザーがアプリをインストールするときにユーザー アクセス トークンを生成する
アプリ設定で [インストール時にユーザーの認可 (OAuth) を要求する] を選んだ場合、GitHub により、ユーザーがアプリをインストールした直後に Web アプリケーション フローが開始されます。
アプリがユーザー アカウントと Organization アカウントのどちらにインストールされるかに関係なく、この方法でユーザー アクセス トークンを生成できます。 ただし、アプリが Organization アカウントにインストールされた場合は、Web アプリケーション フローまたはデバイス フローを使用して、Organization 内の他のユーザーのユーザー アクセス トークンを生成する必要があります。
-
ユーザーがアプリをインストールすると、GitHub でユーザーは
http(s)://HOSTNAME/login/oauth/authorize?client_id=CLIENT_ID
にリダイレクトされます。ここで、CLIENT_ID
はアプリのクライアント ID です。 -
ユーザーが認可要求を受け入れた場合、ユーザーは GitHub でアプリ設定の最初のコールバック URL にリダイレクトされ、
code
クエリ パラメーターが提供されます。どのコールバック URL を使用するかを制御する場合は、 [インストール時にユーザーの認可 (OAuth) を要求する] を選ばないでください。 代わりに、完全な Web アプリケーション フローでユーザーを誘導し、
redirect_uri
パラメーターを指定します。 -
以下のクエリ パラメータと共に、次の URL に
POST
要求を行うことにより、前の手順のcode
をユーザー アクセス トークンに交換します:http(s)://HOSTNAME/login/oauth/access_token
Query parameter (クエリ パラメーター) Type 説明 client_id
string
必須。 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページに移動する方法について詳しくは、「GitHub App 登録の変更」を参照してください。 client_secret
string
必須。 GitHub App のクライアント シークレット。 アプリの設定ページでクライアント シークレットを生成できます。 code
string
必須。 前の手順で受け取ったコード。 redirect_uri
string
認可の後にユーザが送られるアプリケーション中のURL。 これは、GitHub App を設定するときに "コールバック URL" として指定した URL のいずれかと完全に一致する必要があり、追加のパラメーターを含めることはできません。 repository_id
string
ユーザー アクセス トークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。 ユーザー アクセス トークンのアクセスをさらに制限するには、このパラメーターを使います。 -
GitHub から、次のパラメーターを含む応答が提供されます。
応答パラメーター Type 説明 access_token
string
ユーザー アクセス トークン。 トークンは ghu_
で始まります。expires_in
integer
access_token
の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に28800
(8 時間) になります。refresh_token
string
更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_
で始まります。refresh_token_expires_in
integer
refresh_token
の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に15897600
(6 か月) になります。scope
string
トークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。 token_type
string
トークンの種類。 値は常に bearer
になります。 -
前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに 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" \ --header "X-GitHub-Api-Version: 2022-11-28"
更新トークンを使用してユーザー アクセス トークンを生成する
既定では、ユーザー アクセス トークンは 8 時間後に期限切れになります。 有効期限があるユーザー アクセス トークンを受け取った場合は、更新トークンも受け取ります。 更新トークンの有効期限は 6 か月後です。 この更新トークンを使用して、ユーザー アクセス トークンを再生成できます。 詳しくは、「ユーザー アクセス トークンを更新する」を参照してください。
GitHub では、有効期限があるユーザー アクセス トークンを使用することを強くお勧めします。 以前に有効期限があるユーザー アクセス トークンの使用をオプトアウトしたものの、この機能を再び有効化したい場合は、「GitHub アプリのオプション機能のアクティブ化」を参照してください。
トラブルシューティング
次のセクションでは、ユーザー アクセス トークンの生成時に発生する可能性のあるエラーの概要について説明します。
不正なクライアント認識情報
指定した client_id
または client_secret
が正しくない場合は、incorrect_client_credentials
エラーが発生します。
このエラーを解決するには、GitHub App の正しい認証情報を使っていることを確認します。 クライアント ID とクライアント シークレットは、GitHub App の設定ページで確認できます。 GitHub App の設定ページに移動する方法について詳しくは、「GitHub App 登録の変更」をご覧ください。
リダイレクトURIの不一致
GitHub App の登録に対するコールバック URL のいずれとも一致しない redirect_uri
を指定すると、redirect_uri_mismatch
エラーが発生します。
このエラーを解決するには、GitHub App の登録に対するコールバック URL のいずれかと一致する redirect_uri
を指定するか、このパラメーターを省略して、GitHub App の登録に列記されているコールバック URL の最初のものを既定で使います。 詳しくは、「ユーザー承認コールバック URL について」を参照してください。
不正な検証コード
デバイス フローを使っていて、指定した検証コード (device_code
) が正しくない場合、有効期限切れの場合、または http(s)://HOSTNAME/login/device/code
への最初の要求から受け取った値と一致しない場合は、bad_verification_code
エラーが発生します。
このエラーを解決するには、デバイス フローをもう一度開始して、新しいコードを取得する必要があります。 詳しくは、「デバイス フローを使用してユーザー アクセス トークンを生成する」をご覧ください。
更新トークンが正しくない
指定した更新トークンが無効または期限切れである場合は、bad_refresh_token
エラーが発生します。
このエラーを解決するには、Web アプリケーション フローまたはデバイス フローを開始し直して、新しいユーザー アクセス トークンと更新トークンを取得する必要があります。 更新トークンを受け取るのは、GitHub App が期限切れのユーザー アクセス トークンをオプトインしている場合のみです。 詳しくは、「ユーザー アクセス トークンを更新する」を参照してください。
サポートされていない付与タイプ
デバイス フローを介してユーザー アクセス トークンを要求する場合は、grant_type
パラメーターで urn:ietf:params:oauth:grant-type:device_code
を指定する必要があります。 更新トークンを使ってユーザー アクセス トークンを更新する場合は、grant_type
パラメーターで refresh_token
を指定する必要があります。 正しい付与タイプを使わないと、unsupported_grant_type
エラーが発生します。
未確認のユーザー メール
生成しようとしているユーザー アクセス トークンの対象ユーザーのプライマリ メール アドレスが、GitHub で検証されていない場合は、unverified_user_email
エラーが発生します。
このエラーを解決するには、GitHub アカウントでプライマリ メール アドレスを検証するよう、ユーザーに求めます。 詳しくは、GitHub Free のドキュメントの「メールアドレスを検証する」をご覧ください。