Skip to main content

This version of GitHub Enterprise was discontinued on 2022-10-12. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Refreshing user-to-server 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.

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

NameTypeDescription
refresh_tokenstringRequired. The token generated when the GitHub App owner enables expiring tokens and issues a new user access token.
grant_typestringRequired. Value must be refresh_token (required by the OAuth specification).
client_idstringRequired. The client ID for your GitHub App.
client_secretstringRequired. 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.

  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

  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 Optional Features. Optional features tab

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

Further reading