Refreshing user-to-server access tokens

Note: Expiring user tokens are currently in beta and subject to change. 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": "e72e16c7e42f292c6912e7710c838347ae178b4a",
  "expires_in": "28800",
  "refresh_token": "r1.c1b4a2e77838347a7e420ce178f2e7c6912e1692",
  "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.

  1. In the upper-right corner of any page, click your profile photo, then click Settings. Settings icon in the user bar

  2. In the left sidebar, click Developer settings. Developer settings section

  3. In the left sidebar, click GitHub Apps. GitHub Apps section

  4. Click Edit next to your chosen GitHub App. Settings to edit a GitHub App

  5. In the left sidebar, click Beta Features. Beta Features menu option
  6. 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.

Option to opt-in to expiring user tokens during GitHub Apps setup

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."