OAuth 2.0 Hybrid App Refresh Token Flow
Use the OAuth 2.0 hybrid app refresh token flow to give hybrid apps direct management of web sessions after an initial session expires. When the authorizing server grants a new access token using the hybrid_refresh grant type, it includes the session IDs (SID) of the requested domains in its response. The hybrid app can set Lightning, Visualforce, and content domain cookies and use frontdoor.jsp to bridge the access token into a web session, providing uninterrupted service. The hybrid app refresh token flow renews access tokens issued by the OAuth 2.0 web server, user-agent, and hybrid app token flow.
Required Editions
| Available in: both Salesforce Classic (not available in all orgs) and Lightning Experience |
| Available in: All Editions |
See New connected apps can no longer be created in Spring ‘26 for more details.
After a hybrid app—via a connected app—receives an access token, it can use a refresh token to get a new session when its current session expires. The connected app’s session timeout value determines when an access token is no longer valid and when to apply for a new one using a refresh token.
For better security, enable refresh token rotation on your connected app or external client app when you configure its OAuth settings. With this setting enabled, the connected app issues a new refresh token along with the access token each time the flow is invoked. The previous refresh token is automatically invalidated. Refresh token rotation ensures that each refresh token is used only one time per user, so that refresh tokens can’t be used to get new access tokens. If someone tries to use a refresh token that’s been rotated out, Salesforce invalidates the current refresh token and any associated access tokens. To get a new refresh token, the client must complete a new flow.
invalid_grant error when you try to request a token.The hybrid app refresh token flow involves these steps.
- The app uses the existing refresh token to request a new access token.
- After verifying the request, Salesforce grants a new access token to the app.
- The app directly sets the SIDs in the domains’ session cookies and bridges a web session.
Request a New Access Token
The app can use the refresh token to get a new access token by sending a refresh token POST request to the Salesforce token endpoint.
The connected app can send the client_id and
client_secret in the body of the refresh token POST request, as shown
here.
POST /services/oauth2/token HTTP/1.1
Host: login.salesforce.com/
grant_type=hybrid_refresh&
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&
client_secret=1955279925675241571&
refresh_token=your token here
Instead of sending client credentials as parameters in the body of the refresh token POST
request, you can use the HTTP Basic authentication scheme. This scheme’s format requires the
client_id and client_secret in the authorization header
of the post: Authorization: Basic64Encode(client_id:secret).
The client_id and client_secret are separated with a
colon (:). For more information, see the OAuth 2.0 Authorization Framework.
This example shows a hybrid app refresh token POST request that uses the HTTP Basic authentication scheme rather than sending client credentials in the POST request’s body.
POST /services/oauth2/token HTTP/1.1
Host: login.salesforce.com
Authorization: Basic
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&
client_secret=1955279925675241571
grant_type=hybrid_refresh&
refresh_token=your token here
client_id and client_secret are sent in the
POST’s body, the authorization header is ignored.With either refresh token POST request format, include these parameters.
| Parameter | Description |
|---|---|
client_id
|
The consumer key of the connected app. To access the consumer key, from the App Manager, find the connected app and select View from the dropdown. Then click Manage Consumer Details. You're sometimes prompted to verify your identity before you can view the consumer key. |
client_secret
|
The consumer secret of the connected app. To access the consumer secret, from the App Manager, find the connected app and select View from the dropdown. Then click Manage Consumer Details. You're sometimes prompted to verify your identity before you can view the consumer secret. |
grant_type
|
The OAuth 2.0 grant type that the connected app requests. The value must be
hybrid_refresh for this flow. |
refresh_token
|
Token obtained from the web server, user-agent, or hybrid app token flow. This
value is a secret. Take appropriate measures to protect it. This parameter is
returned only if your connected app is set up with a refresh_token
scope. |
client_assertion
|
Instead of passing a client_secret, you can provide a
client_assertion and client_assertion_type. If a
client_secret parameter isn’t provided, Salesforce checks for the
client_assertion and client_assertion_type. See
Use client_assertion Instead of
client_secret. |
client_assertion_type
|
Provide this value when using the The value of |
format
|
If not included in the request’s header, you can specify the expected return
format. The
|
Salesforce Grants a New Access Token
After verifying the request, Salesforce sends a response with a new access token to the app. Here’s an example JSON response from Salesforce.
{ "id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448384422",
"instance_url":"https://yourInstance.salesforce.com/",
"signature":"SSSbLO/gBhmmyNUvN18ODBDFYHzakxOMgqYtu+hDPsc=",
"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNBaT1cyWk7TrqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4",
"token_type":"Bearer",
"scope":"web visualforce refresh_token lightning content",
"cookie-clientSrc":"10.xxx.xx.xx",
"sidCookieName":"sid",
"cookie-sid_Client":"0000000...",
"content_domain":"MyDomainName.file.force.com",
"content_sid":"00Dxx0000006Gb…",
"lightning_domain":"MyDomainName.lightning.force.com",
"lightning_sid”:”00Dxx000000…",
"csrf_token":"ABCD…",
"visualforce_domain":"MyDomainName.vf.force.com",
"visualforce_sid":"00Dxx000000…"}
And here’s an example XML response.
<Oauth>
<access_token>00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNB...</access_token>
<token_type>Bearer</token_type>
<scope>web visualforce refresh_token lightning content</scope>
<cookie-clientSrc>10.xxx.xx.xx</cookie-clientSrc>
<sidCookieName>sid</sidCookieName>
<cookie-sid_Client>0000000...</cookie-sid_Client>
<content_domain>MyDomainName.file.force.com</content_domain>
<content_sid>00Dxx0000006Gb…</content_sid>
<lightning_domain>MyDomainName.lightning.force.com</lightning_domain>
<lightning_sid>00Dxx000000…</lighning_sid>
<csrf_token>ABCD…</csrf_token>
<visualforce_domain>MyDomainName.vf.force.com</visualforce_domain>
<visualforce_sid>00Dxx000000…</visualforce_sid>
<instance_url>https://yourInstance.salesforce.com/</instance_url>
<id>https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P</id>
<issued_at>1278448101416</issued_at>
<signature>CMJ4l+CCaPQiKjoOEwEig9H4wqhpuLSk4J2urAe+fVg=</signature>
</Oauth>
This example shows a URL-encoded response.
access_token=00Dx0000000BV7z%21AR8AQP0jITN80ESEsj5E...&
token_type=Bearer&
instance_url=https%3A%2F%2FyourInstance.salesforce.com&
id=https://login.salesforce.com%2Fid%2F00Dx0000000BV7z%2F005x00000012Q9P&
issued_at=1278448101416&
signature=CMJ4l%2BCCaPQiKjoOEwEig9H4wqhpuLSk4J2...
cookie-clientSrc=10.xxx.xx.xx&
content_domain=MyDomainName.file.force.com&
content_sid=00Dxx0000006Gb...&
lightning_domain=MyDomainName.lightning.force.com&
lightning_sid=00Dxx000000...&
csrf_token=ABCD...&
visualforce_domain=MyDomainName.vf.force.com&
visualforce_sid=00Dxx000000...&
scope=web+visualforce+refresh_token+lightning+content&
sidCookieName=sid&
cookie-sid_Client=0000000...&
The following parameters can be included in the body of the response.
| Parameter | Description |
|---|---|
access_token
|
OAuth token that a connected app uses to request access to a protected resource on behalf of the client application. Additional permissions in the form of scopes can accompany the access token. |
token_type
|
A Bearer token type, which is used for all responses that
include an access token. |
instance_url
|
A URL indicating the instance of the user’s org. For example:
https://yourInstance.salesforce.com/. |
id
|
An identity URL that can be used to identify the user and to query for more information about the user. See Identity URLs. |
issued_at
|
Time stamp of when the signature was created in milliseconds. |
signature
|
Base64-encoded HMAC-SHA256 signature signed with the
client_secret. The signature can include the concatenated ID and
issued_at value, which you can use to verify that the identity
URL hasn’t changed since the server sent it. |
sfdc_site_url
|
If the user is a member of an Experience Cloud site, the site URL is provided. |
sfdc_site_id
|
If the user is a member of an Experience Cloud site, the user’s site ID is provided. |
content_domain
|
The domain of the content session, which maps to the content SID:
You receive this value only if you assign the
|
content_sid
|
The SID associated with the domain of the content session. Salesforce returns a unique SID that the hybrid app directly sets in the domain’s session cookie. You
receive this value only if you assign the |
lightning_domain
|
The domain of the Lightning session, which maps to the Lightning SID:
You receive this value only if you assign the
|
lightning_sid
|
The SID associated with the domain of the Lightning session. Salesforce returns a unique SID that the hybrid app directly sets in the domain’s session cookie. You
receive this value only if you assign the |
visualforce_domain
|
The domain of the Visualforce session, which maps to the Visualforce SID:
You receive this value only if you assign the
|
visualforce_sid
|
The SID associated with the domain of the Visualforce session. Salesforce returns a unique SID that the hybrid app directly sets in the domain’s session cookie. You receive this value only if you assign the
|
csrf_token
|
The cross-site request forgery (CSRF) token to prevent attacks during child sessions. You receive this value only if you assign the
|
scope
|
The scopes associated with the access token. Scopes further define the type of protected resources that the client can access. You assign scopes to a connected app when you build it, and they’re included with the OAuth tokens during the authorization flow. For valid parameters, see OAuth Scopes. |
sidCookieName
|
The name of the session cookie that the hybrid app uses to directly bridge a
web session. The default value is sid. |
cookie-sid_Client
|
A session cookie that detects and prevents session tampering. This session cookie allows the hybrid app to directly bridge a web session. |
cookie-clientSrc
|
A session cookie that is used for security protections. This session cookie allows the hybrid app to directly bridge a web session. |
parent_sid
|
A SID that's associated with the user's parent UI session. The
|
App Sets Domain SIDs and Bridges a Web Session
The hybrid app sets the domains’ associated SIDs in the session cookies to directly bridge a web session.
For implementations that are resetting user division on objects for the Reset to Default Division on Login setting, the hybrid app must bridge a web session using frontdoor.jsp. For more information, see Using Frontdoor.jsp to Bridge Sessions into Salesforce. To learn more about user divisions, see Organize Data with Divisions.
