Refresh the access and ID tokens

Identity Engine

This guide shows you how to refresh access and ID tokens by using either the Identity Engine SDK or the OIDC & OAuth 2.0 API.

---

Learning outcome

• Understand how access and ID tokens have a limited lifetime.
• Know how to use refresh tokens when access and ID tokens expire.

What you need

• An Okta org that is already configured for your use case
• An Identity Engine SDK that is set up for your own app
• An app that uses an Identity Engine SDK that is configured with an offline_access scope

---

Overview

Access tokens often have limited lifetimes. If you allow access tokens to expire, their usefulness is limited in the event an attacker discovers them. For your app to continue to use the appropriate resources when an access token expires, the app can refresh them without user intervention by using a refresh token.

All the SDKs expose functionality that allows you to obtain access, ID, and refresh tokens. Each SDK (Swift, JavaScript, and so on) has a different set of convenience methods and other functionality that provide you with built-in support for token refresh, auto-renewal, and storage. Minimally, all the SDKs allow you to obtain the refresh token and call the authorization server's token endpoint to renew the access token.

Refresh the tokens

You can refresh tokens with the SDK or with the OAuth token endpoint.

Refresh the tokens with the SDK

The JavaScript SDK has built-in support for the auto-renewing of access and ID tokens. This behavior is enabled by default, but you can disable it by setting the tokenManager autoRenew property to false.

const authClient = new OktaAuth({
    tokenManager: {
      autoRenew: false
    }
  });

If the autoRenew property is set to false, you can still manually refresh tokens by subscribing to the tokenManager expired event and calling its renew method.

authClient.tokenManager.on('expired', function (key, expiredToken) {
  //do something
});

See the following links to the SDK repository readme (opens new window) for more information on these methods and events:

• tokenManager autoRenew property (opens new window)
• tokenManager expired event (opens new window)
• tokenManager renew method (opens new window)

Note: The direct API approach using the OAuth token endpoint is also supported for refresh tokens. However, this approach is discouraged because it requires you to implement token storage, rotation, and other token refresh functionality.

Refresh the tokens with the OAuth token endpoint

You can refresh access and ID tokens using the /token endpoint with the grant_type set to refresh_token. Before calling this endpoint, obtain the refresh token from the SDK and ensure that you've included offline_access as a scope in the SDK configurations. For further details on access token refresh with this endpoint, see Use a refresh token.

Web applications

Web applications refresh access tokens by calling the /token endpoint and passing in a required Authorization header. This header is computed from the client ID and secret.

Request example

POST /oauth2/default/v1/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MG9hMTJncG5qZnpvdllTbk41ZDc6UG9zWGpjNmw0WHF5ZDBhek03cjF0SnhyMS1LWHdWYmNFaDk0Q0FDNA==

grant_type: refresh_token
redirect_uri: http://localhost:8080
scope: offline_access openid profile
refresh_token: 03_hBtVj-Hk0Mxo9TPSdl7TLkxQioKqQEzud3ldqHqs

Native and SPA applications

OIDC and OAuth 2.0 requests for native and single-page applications (SPAs) don't include the Authorization header with the client ID and secret. Instead, these apps include the client_id query parameter in their requests.

Request example

POST /oauth2/default/v1/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
redirect_uri=com.embeddedauth://callback
scope=offline_access openid profile
refresh_token=03_hBtVj-Hk0Mxo9TPSdl7TLkxQioKqQEzud3ldqHqs
client_id=0oa94el1z4nUDxx0z5d7

Response example

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJraWQiOiJoQkZNR...",
    "scope": "offline_access openid profile",
    "refresh_token": "HRzOBfj1A1g6akWqNHfCE-KX-9NASmnFqhRFOt_rEdc",
    "id_token": "eyJraWQiOiJoQkZN..."
}

Use the introspect endpoint to get token info

To get information on a current token, such as if the token is active or has expired, use the /introspect endpoint.

Web applications

Web applications request for token information by calling the /introspect endpoint and passing in a required Authorization header. This header is computed from the client ID and secret.

Request example

POST /oauth2/default/v1/introspect HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MG9hMTJncG5qZnpvdllTbk41ZDc6UG9zWGpjNmw0WHF5ZDBhek03cjF0SnhyMS1LWHdWYmNFaDk0Q0FDNA==

token=eyJraWQiOiJoQk...
token_type_hint=access_token

Native and SPA applications

OIDC and OAuth 2.0 requests for native and single-page applications (SPAs) don't include the Authorization header with the client ID and secret. Instead, these apps include the client_id query parameter in their requests.

Request example

POST /oauth2/default/v1/introspect HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded

token=eyJraWQiOiJoQk...
client_id=0oa14dl1z4nUJxx0z5d7
token_type_hint=access_token

Response example

{
    "active": true,
    "scope": "profile openid offline_access",
    "username": "foo@bar.com",
    "exp": 1626128470,
    "iat": 1626124870,
    "sub": "foo@bar.com",
    "aud": "api://default",
    "iss": "https://dev-12345678.okta.com/oauth2/default",
    "jti": "AT.4PAhL3RW5Yxn5leKbT3_xpiflVWYvcrKtzgkt9HHwDo.oar2str41LSUbsgXb5d6",
    "token_type": "Bearer",
    "client_id": "0oa14dl1z4nUJxx0z5d7",
    "uid": "00u128itb5sYrGii55d7"
}