Refreshing Access Tokens

The lifetime of an access token depends on how you acquired the token. When you get a token, the expires_in field indicates how long, in seconds, the token is valid for. When a token expires, it becomes invalid. If you call a Twitch API with an invalid token, the request returns 401 Unauthorized.

Although you could use the expires_in value to proactively get a new token before the token expires, you’re discouraged from using this approach because tokens can become invalid for a number of reasons (see How do tokens become invalid?). Instead, Twitch recommends that apps reactively respond to HTTP status code 401 Unauthorized.

The only access tokens that apps can refresh without requesting user consent are user access tokens created using the OAuth Authorization Code Grant Flow. When you get a user access token using the Authorization Code Grant flow, you also get a refresh token. Generally, refresh tokens are used to extend the lifetime of a given authorization. Your app uses the refresh token to get a new access token after receiving a 401 Unauthorized response.

NOTE You cannot refresh app access tokens.

The following example shows the JSON object that the https://id.twitch.tv/oauth2/token endpoint returns. The object includes an access token and a refresh token. You must safely store both the access token and the refresh token.

{
  "access_token": "0123456789abcdefghijABCDEFGHIJ",
  "refresh_token": "eyJfaWQmNzMtNGCJ9%6VFV5LNrZFUj8oU231/3Aj",
  "expires_in": 5215742,
  "scope": "channel:read:subscriptions",
  "token_type": "bearer"
}

How to use a refresh token

To refresh a user access token, send an HTTP POST request to https://id.twitch.tv/oauth2/token. The following table lists the x-www-form-urlencoded parameters that you pass in the body of the request.

Parameter	Required?	Type	Description
client_id	Yes	String	Your app’s client ID. See Registering your app.
client_secret	Yes	String	Your app’s client secret. See Registering your app.
grant_type	Yes	String	Must be set to `refresh_token`.
refresh_token	Yes	String	The refresh token issued to the client. You must URL encode the refresh token before posting the request. If you don’t, and the token contains restricted characters, the request may fail with “Invalid refresh token”.

The following cURL example shows a refresh request. Remember to URL encode your refresh token.

curl -X POST https://id.twitch.tv/oauth2/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=refresh_token&refresh_token=gdw3k62zpqi0kw01escg7zgbdhtxi6hm0155tiwcztxczkx17&client_id=<your client id goes here>&client_secret=<your client secret goes here>'

If the request succeeds, the response contains the new access token, refresh token, and scopes associated with the new grant. Because refresh tokens may change, your app should safely store the new refresh token to use the next time.

{
  "access_token": "1ssjqsqfy6bads1ws7m03gras79zfr",
  "refresh_token": "eyJfMzUtNDU0OC4MWYwLTQ5MDY5ODY4NGNlMSJ9%asdfasdf=",
  "scope": [
    "channel:read:subscriptions",
    "channel:manage:polls"
  ],
  "token_type": "bearer"
}

The following example shows what the response looks like if the request fails.

{
  "error": "Bad Request",
  "status": 400,
  "message": "Invalid refresh token"
}

Can a refresh token become invalid?

Yes, refresh tokens can become invalid. Refresh tokens, like access tokens, can become invalid if the user changes their password or disconnects your app. Most refresh tokens do not expire, but refresh tokens generated by a Public client type will expire 30 days after they are generated, which will invalidate the refresh token. Most applications are set to the Confidential client type, of which the refresh tokens do not have an expiration time.

A refresh request can fail with HTTP status code 401 Unauthorized if the refresh token is no longer valid. If the refresh fails, the application should re-prompt the end user for consent using the Authorization Code Grant flow or OIDC Authorization Code Grant flow.

Handling token refreshes in a multi-threaded app

At any given point in time, the maximum number of valid access tokens that a refresh token can be associated with is 50. If a refresh token has 50 valid access tokens associated with it and you try to create the 51st, the request fails. This limit might become an issue if multiple threads sharing the same authorization try to simultaneously refresh the access token. In this case, it’s possible that the refresh request may fail for some of the threads after the refresh token reaches the 50 access token limit.

For multi-threaded apps, Twitch recommends that your app refresh the access token in one thread, which then distributes the new access token to the other threads.