Using Refresh Tokens

At the same time as you obtain an OAuth access token, you can also choose to obtain a refresh token. If you choose to obtain a refresh token, it can be used to obtain a new access token when the previous token expires. Refresh tokens are optional, but using them avoids the need for re-authentication every time an access token expires.

When you use a refresh token to retrieve a new access token, the new token is generated using the expiry of the scope you passed in the initial access token request.

Enabling Refresh Tokens

To enable refresh tokens, you must edit the IDCS Confidential Application and enable the "Refresh Token" grant type. This step requires you log in to the IDCS Administration Console with a user assigned to the IDCS Administrator role.

Obtaining Refresh Tokens

To obtain a refresh token, you must add "offline_access" to the scope object you use when you call the IDCS /oauth2/v1/token endpoint. For example:

urn:opc:idm:__myscopes__ offline_access

The response will include a refresh token as well as the OAuth access token. For example:

{'access_token': '<OAUTH_ACCESS_TOKEN>', 'token_type': 'Bearer', 'expires_in': <TOKEN_EXPIRY>, 'refresh_token': '<REFRESH_TOKEN>'}

Using Refresh Tokens

To use the refresh token to generate a new access token, you must call your /oauth2/v1/token endpoint using the refresh_token grant type.

Here is an example call to generate a refresh token using Client ID and Client Secret:

POST https://<IDCSTenantURL>/oauth2/v1/token 
       
      Headers: 
        Content-Type: application/x-www-form-urlencoded 
        Authorization: Basic <BASE64ENCODED_CLIENTID:CLIENTSECRET> 
       
      Body (newlines for clarity): 
        grant_type=refresh_token 
        &refresh_token=<REFRESH_TOKEN>

Here is an example call to generate a refresh token using JWT client assertion:

POST https://<IDCSTenantURL>/oauth2/v1/token 
       
      Headers: 
        Content-Type: application/x-www-form-urlencoded 
       
      Body (newlines for clarity): 
        grant_type=refresh_token 
        &refresh_token=<REFRESH_TOKEN> 
        &client_id=<IDCS_CONFIDENTIALAPPLICATION_CLIENTID> 
        &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer 
        &client_assertion=<BASE64ENCODED_JWT_CLIENT_ASSERTION>