refreshing-user-access-tokens.md

title	Refreshing user access tokens
intro	To enforce regular token rotation and reduce the impact of a compromised token, you can configure your {% data variables.product.prodname_github_app %} to use user access tokens that expire.
redirect_from	/apps/building-github-apps/refreshing-user-to-server-access-tokens /developers/apps/refreshing-user-to-server-access-tokens /developers/apps/building-github-apps/refreshing-user-to-server-access-tokens /apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-to-server-access-tokens
versions	fpt ghes ghec * * *
shortTitle	Refresh user access tokens
category	Authenticate with a GitHub App

About user access tokens that expire

Note

User access tokens that expire are currently an optional feature and are subject to change. For more information, see Expiring user-to-server access tokens for GitHub Apps.

To enforce regular token rotation and reduce the impact of a compromised token, you can configure your {% data variables.product.prodname_github_app %} to use user access tokens that expire. If your app uses user access tokens that expire, then you will receive a refresh token when you generate a user access token. The user access token expires after eight hours, and the refresh token expires after six months. For more information, see AUTOTITLE.

You can use the refresh token to generate a new user access token and a new refresh token. Once you use a refresh token, that refresh token and the old user access token will no longer work.

If your refresh token expires before you use it, you can regenerate a user access token and refresh token by sending users through the web application flow or device flow. For more information, see AUTOTITLE.

{% ifversion github-app-offline-access %}

To test and gradually roll out support for expiring tokens, you can opt in for an individual user authorization by requesting the offline_access scope. When you request offline_access, you will receive an expiring user access token and a refresh token even if your app is configured not to use expiring user access tokens.

The scope parameter does not grant permissions to a {% data variables.product.prodname_github_app %}. The only supported value is offline_access, which forces the user access token to expire.

{% endif %}

Configuring your app to use user access tokens that expire

When you create your app, expiration of user access tokens is enabled unless you opt out. For more information, see AUTOTITLE. You can also configure this setting after your app has been created.

{% data reusables.apps.settings-step %} {% data reusables.apps.enterprise-apps-steps %}

1. Next to the {% data variables.product.prodname_github_app %} that you want to modify, click Edit.

2. In the {% data variables.product.prodname_github_apps %} settings sidebar, click Optional Features.

3. Next to "User-to-server token expiration", click Opt-in or Opt-out. This setting may take a couple of seconds to apply.

   {% data variables.product.company_short %} recommends that you opt in to this feature for improved security.

If you re-enable expiring user access tokens after you've already signed in users and gotten their access token, those pre-existing user access tokens will not expire. You should delete these tokens by using the DELETE /applications/CLIENT_ID/token endpoint or have the users reauthenticate so that they get an expiring token. For more information, see AUTOTITLE.

Refreshing a user access token with a refresh token

1. Make a POST request to this URL, along with the following query parameters: {% data variables.product.oauth_host_code %}/login/oauth/access_token

   Query parameter	Type	Description
   client_id	string	Required. The client ID for your {% data variables.product.prodname_github_app %}. The client ID is different from the app ID. You can find the client ID on the settings page for your app.
   client_secret	string	Required unless the user access token was generated using the device flow. The client secret for your {% data variables.product.prodname_github_app %}.
   grant_type	string	Required. The value must be "refresh_token".
   refresh_token	string	Required. The refresh token that you received when you generated a user access token.

2. {% data variables.product.company_short %} will give a response that includes the following parameters:

   {% data reusables.apps.user-access-token-response-parameters %}