Refresh Tokens with OAuth 2.0

LinkedIn has introduced Refresh Tokens with OAuth 2.0.  This feature is currently available for a limited set of partners. It will be made GA in the near future.

Introduction

Refresh tokens are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires. For more information, please refer to this section from the OAuth 2.0 RFC.

LinkedIn offers static refresh tokens. Here static refers to the fixed duration until which a refresh token is valid. When a refresh token is exchanged for a new Access Token,  the TTL of the Refresh Token remains unchanged with respect to the TTL specified in the initial Oauth flow.

For example: If the refresh token has a TTL of 30 days and after 21 days the refresh token is used to generate a new access token and new refresh token. The new refresh token will have a TTL of 9 days only.

This implies that the user will have to eventually re-auth after the Access Token and Refresh Token expire. By default, the Access Tokens will be valid for 60 days and Refresh Token will be valid for a year.

API Usage:

Step 1 — Getting a Refresh Token

In order to use Refresh Tokens,  you need to first use OAuth 2.0 authentication.  Please refer this guide to setup your application to make authenticated requests.    

When exchanging Authorization Code for an Access Token, If Refresh Tokens are enabled,  the following fields will also be returned:

  • refresh_token — The refresh token for the user.  This value must also be kept secure, as per your agreement to the API Terms of Use.
  • refresh_token_expires_in — The number of seconds remaining before the refresh token will expire.  The lifespan of refresh tokens is usually larger than Access tokens. The exact duration depends on the type of Refresh Tokens issued. The different types explained below in the document.
sample response
{
  "access_token": "AQXNnd2kXITHELmWblJigbHEuoFdfRhOwGA0QNnumBI8XOVSs0HtOHEU-wvaKrkMLfxxaB1O4poRg2svCWWgwhebQhqrETYlLikJJMgRAvH1ostjXd3DP3BtwzCGeTQ7K9vvAqfQK5iG_eyS-q-y8WNt2SnZKZumGaeUw_zKqtgCQavfEVCddKHcHLaLPGVUvjCH_KW0DJIdUMXd90kWqwuw3UKH27ki5raFDPuMyQXLYxkqq4mYU-IUuZRwq1pcrYp1Vv-ltbA_svUxGt_xeWeSxKkmgivY_DlT3jQylL44q36ybGBSbaFn-UU7zzio4EmOzdmm2tlGwG7dDeivdPDsGbj5ig",
  "expires_in": 86400,
  "refresh_token": "AQWAft_WjYZKwuWXLC5hQlghgTam-tuT8CvFej9-XxGyqeER_7jTr8HmjiGjqil13i7gMFjyDxh1g7C_G1gyTZmfcD0Bo2oEHofNAkr_76mSk84sppsGbygwW-5oLsb_OH_EXADPIFo0kppznrK55VMIBv_d7SINunt-7DtXCRAv0YnET5KroQOlmAhc1_HwW68EZniFw1YnB2dgDSxCkXnrfHYq7h63w0hjFXmgrdxeeAuOHBHnFFYHOWWjI8sLenPy_EBrgYIitXsAkLUGvZXlCjAWl-W459feNjHZ0SIsyTVwzAQtl5lmw1ht08z5Du-RiQahQE0sv89eimHVg9VSNOaTvw",
  "refresh_token_expires_in": 525600
}

The length of Refresh Tokens is ~500 characters. We recommend that you plan for your application stack to handle tokens with length of at least 1000 characters in order to accommodate current and any future expansion plans. This applies to both access tokens as well as refresh tokens.

Step 2 — Exchanging Refresh Token for a new Access Token

You can exchange the Refresh Token for a new Access Token by making the following "x-www-form-urlencoded" HTTP POST request:

POST
https://www.linkedin.com/oauth/v2/accessToken
Parameter Description Required
grant_type The value of this field should always be:  refresh_token Yes
refresh_token The refresh token you have from Step 1. Yes
client_id
The "API Key" of your app. Yes
client_secret
The "Secret Key" of your app. Yes
sample call
POST /oauth/v2/accessToken HTTP/1.1
Host: www.linkedin.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=AQQOMeCIQMa6-zjU-02w8EJW67wPVk3hjJE5x1lZhU013LihKD8i1DpvaAl2jnuP8F1uXMgkm8nzjPfnaJR_kQNOxsLRLZWnAMzHMm81S0yQlkBYicw&client_id=861hhm46p48to2&client_secret=gPecS7yqHkyyShvR

A successful request will return a new Access Token with a new expiration time and also return the refresh token.

sample response
{
  "access_token": "BBBB2kXITHELmWblJigbHEuoFdfRhOwGA0QNnumBI8XOVSs0HtOHEU-wvaKrkMLfxxaB1O4poRg2svCWWgwhebQhqrETYlLikJJMgRAvH1ostjXd3DP3BtwzCGeTQ7K9vvAqfQK5iG_eyS-q-y8WNt2SnZKZumGaeUw_zKqtgCQavfEVCddKHcHLaLPGVUvjCH_KW0DJIdUMXd90kWqwuw3UKH27ki5raFDPuMyQXLYxkqq4mYU-IUuZRwq1pcrYp1Vv-ltbA_svUxGt_xeWeSxKkmgivY_DlT3jQylL44q36ybGBSbaFn-UU7zzio4EmOzdmm2tlGwG7dDeivdPDsGbj5ig",
  "expires_in": 86400,
  "refresh_token": "AQWAft_WjYZKwuWXLC5hQlghgTam-tuT8CvFej9-XxGyqeER_7jTr8HmjiGjqil13i7gMFjyDxh1g7C_G1gyTZmfcD0Bo2oEHofNAkr_76mSk84sppsGbygwW-5oLsb_OH_EXADPIFo0kppznrK55VMIBv_d7SINunt-7DtXCRAv0YnET5KroQOlmAhc1_HwW68EZniFw1YnB2dgDSxCkXnrfHYq7h63w0hjFXmgrdxeeAuOHBHnFFYHOWWjI8sLenPy_EBrgYIitXsAkLUGvZXlCjAWl-W459feNjHZ0SIsyTVwzAQtl5lmw1ht08z5Du-RiQahQE0sv89eimHVg9VSNOaTvw",
  "refresh_token_expires_in": 439200
}