Note: Expiring user tokens are currently an optional feature and subject to change. To opt in or out of the user-to-server token expiration feature, see "Activating optional features for apps." For more information, see "Expiring user-to-server access tokens for GitHub Apps."
About expiring user access tokens
To enforce regular token rotation and reduce the impact of a compromised token, you can configure your GitHub App to use expiring user access tokens. For more information on making user-to-server requests, see "Identifying and authorizing users for GitHub Apps."
Expiring user tokens expire after 8 hours. When you receive a new user-to-server access token, the response will also contain a refresh token, which can be exchanged for a new user token and refresh token. Refresh tokens are valid for 6 months.
Renewing a user token with a refresh token
To renew an expiring user-to-server access token, you can exchange the refresh_token for a new access token and refresh_token.
POST https://github.com/login/oauth/access_token
This callback request will send you a new access token and a new refresh token. This callback request is similar to the OAuth request you would use to exchange a temporary code for an access token. For more information, see "Identifying and authorizing users for GitHub Apps" and "Basics of authentication."
Parameters
| Name | Type | Description |
|---|---|---|
refresh_token | string | Required. The token generated when the GitHub App owner enables expiring tokens and issues a new user access token. |
grant_type | string | Required. Value must be refresh_token (required by the OAuth specification). |
client_id | string | Required. The client ID for your GitHub App. |
client_secret | string | Required. The client secret for your GitHub App. |
Response
{
"access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
"expires_in": "28800",
"refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
"refresh_token_expires_in": "15811200",
"scope": "",
"token_type": "bearer"
}
Configuring expiring user tokens for an existing GitHub App
You can enable or disable expiring user-to-server authorization tokens from your GitHub App settings.
-
In the upper-right corner of any page, click your profile photo, then click Settings.
-
In the left sidebar, click Developer settings.
-
In the left sidebar, click GitHub Apps.
-
Click Edit next to your chosen GitHub App.
-
In the left sidebar, click Optional Features.
-
Next to "User-to-server token expiration", click Opt-in or Opt-out. This setting may take a couple of seconds to apply.
Opting out of expiring tokens for new GitHub Apps
When you create a new GitHub App, by default your app will use expiring user-to-server access tokens.
If you want your app to use non-expiring user-to-server access tokens, you can deselect "Expire user authorization tokens" on the app settings page.
Existing GitHub Apps using user-to-server authorization tokens are only affected by this new flow when the app owner enables expiring user tokens for their app.
Enabling expiring user tokens for existing GitHub Apps requires sending users through the OAuth flow to re-issue new user tokens that will expire in 8 hours and making a request with the refresh token to get a new access token and refresh token. For more information, see "Identifying and authorizing users for GitHub Apps."
