Get a refresh token

To get a refresh token, you send a request to your Okta Authorization Server.

The only flows that support refresh tokens are the authorization code flow and the resource owner password flow. This means that the following combinations of grant type and scope, when sent to the /token endpoint, return a refresh token:

Note: The maximum length for the scope parameter value is 1024 characters.

Grant Type	Scope
authorization_code	offline_access (see Note)
refresh_token	offline_access
password	offline_access

Notes: The authorization code flow is unique in that the offline_access scope must be requested as part of the code request to the /authorize endpoint and not the request sent to the /token endpoint.

Whether persistent refresh token or rotating refresh token behavior is enabled depends on what type of application that you are using. When you select Refresh Token as an allowed grant type, SPAs use refresh token rotation as the default behavior. Native apps and web apps use persistent refresh token behavior as the default. See Refresh token rotation.

Get a refresh token with the code flow

In the case of the authorization code flow, you use the Authorization Server's /authorize endpoint to get an authorization code, specifying an offline_access scope. You then use the authorization_code grant with this code in a request to the /token endpoint to get an access token and a refresh token.

See Obtain an authorization grant from a User and Implementing the authorization code flow for more information on the /authorize endpoint and the authorization code flow.

Example request for an authorization code and refresh token

The following is an example request to the /authorize endpoint for an authorization code flow and includes the offline_access scope.

GET https://${yourOktaDomain}/oauth2/default/v1/authorize?client_id=${clientId}
 &response_type=code
 &scope=openid%20offline_access
 &redirect_uri=ourApp%3A%2Fcallback
 &state=237c671a-29d7-11eb-adc1-0242ac120002

The following is an example request to the /authorize endpoint for an authorization code with PKCE flow and includes the offline_access scope.

https://${yourOktaDomain}/oauth2/default/v1/authorize?client_id=${clientId}
&response_type=code
&scope=openid%20offline_access
&redirect_uri=yourApp%3A%2Fcallback
&state=4ff7dcc0-29d7-11eb-adc1-0242ac120002
&code_challenge_method=S256
&code_challenge=qjrzSW9gMiUgpUvqgEPE4_-8swvyCtfOVvg55o5S_es

Example request for an access token, ID token, and refresh token

The following is an example request to the /token endpoint to obtain an access token, an ID token (by including the openid scope), and a refresh token for the Authorization Code flow. The value for code is the authorization code that you receive in the response from the request to the /authorize endpoint.

curl --location --request POST 'https://${yourOktaDomain}/oauth2/default/v1/token' \
-H 'Accept: application/json' \
-H 'Authorization: Basic ${Base64(${clientId}:${clientSecret})}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code' \
-d 'redirect_uri=${redirectUri}' \
-d 'code=iyz1Lpim4NgN6gDQdT1a9PJDVTaCdxG1wJMYiUkfGts' \
-d 'state=9606b31k-51d1-4dca-987c-346e3d8767n9' \
-d 'scope=openid offline_access'

The following is an example request to the /token endpoint to obtain an access token, an ID token (by including the openid scope), and a refresh token for the Authorization Code with PKCE flow. The value for code is the code that you receive in the response from the request to the /authorize endpoint.

curl --location --request POST 'https://${yourOktaDomain}/oauth2/default/v1/token' \
-H 'Accept: application/json' \
-H 'Authorization: Basic ${Base64(${clientId}:${clientSecret})}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code' \
-d 'redirect_uri=${redirectUri}' \
-d 'code=iyz1Lpim4NgN6gDQdT1a9PJDVTaCdxG1wJMYiUkfGts' \
-d 'state=419946f0-29d7-11eb-adc1-0242ac120002' \
-d 'scope=openid offline_access' \
-d 'code_verifier=M25iVXpKU3puUjFjYWg3T1NDTDQtcW1rOUY5YXlwalNoc0hhaoxifmZHag'

Example response

Note: The access and ID tokens are truncated for brevity.

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJraWQ.....rm8EA4osYg",
    "scope": "offline_access openid",
    "refresh_token": "i6mapTIAVSp2oJkgUnCACKKfZxt_H5MBLiqcybBBd04",
    "id_token": "eyJraWQiOiJ.....XAn3ty6o-yeA"
}

Get a refresh token with the resource owner password flow

For the resource owner password flow, you use the authorization server's /token endpoint directly.

See Request a token and Implementing the resource owner password flow for more information on the /token endpoint and the resource owner password flow.

Example request

With the password grant type, you can include an openid scope alongside the offline_access scope to also get back an ID token.

curl --location --request POST 'https://${yourOktaDomain}/oauth2/default/v1/token' \
-H 'Accept: application/json' \
-H 'Authorization: Basic ${Base64(${clientId}:${clientSecret})}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=password' \
-d 'redirect_uri=${redirectUri}' \
-d 'username=example@mailinator.com' \
-d 'password=a.gReAt.pasSword' \
-d 'scope=openid offline_access'

Example response

You would then get back an ID token as well as your access and refresh tokens. See the Okta OAuth 2.0 reference page.

Note: The access and ID tokens are truncated for brevity.

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJraWQi.....T2aA5ottg",
    "scope": "offline_access openid",
    "refresh_token": "cBMrwDsXRwPqVmCQx7I5IX0jQ9-Lc_zHOgYeab1xZm4",
    "id_token": "eyJra.....ezAriw"
}

Renew access and ID tokens with SPAs

With a SPA, it is usually undesirable to redirect the user to a sign-in page during normal navigation. To avoid this disruptive redirection, the /authorize endpoint allows the use of a request parameter called prompt. If the value of the prompt parameter is none, this guarantees that the user won't be prompted to sign in, regardless of whether they have an active session. Instead, your application either silently obtains the requested tokens or an OAuth error response occurs. Before refresh token rotation was available, the prompt parameter was the only way for a SPA to maintain user sessions without prompting the user to sign in multiple times.

The introduction of browser privacy controls such as Intelligent Tracking Prevention (ITP) and Enhanced Tracking Prevention (ETP) affect how browsers handle third-party cookies. These browser privacy controls prevent the use of an Okta session cookie to silently renew user sessions, which forces the user to reauthenticate and takes away the seamless user experience. Refresh token rotation provides a solution for SPAs to maintain user sessions in an ITP browser world. Since refresh tokens are independent of any cookies, you don't have to rely on an Okta session cookie to renew access and ID tokens.

Note: You can still use the Okta session cookie and silently renew the tokens as long as the application and Okta are in the same domain.

Next: Use a refresh token