Loading
Salesforce now sends email only from verified domains. Read More
Identify Your Users and Manage Access
Table of Contents
Filter by (0)Add
Select Filters

          No results
          No results
          Here are some search tips

          Check the spelling of your keywords.
          Use more general search terms.
          Select fewer filters to broaden your search.

            Search all of Salesforce Help
            Search all of Salesforce Help
            OAuth 2.0 Refresh Token Flow for Renewed Sessions

            You are here:

            1. Salesforce Help
            2. Docs
            3. Identify Your Users and Manage Access

            OAuth 2.0 Refresh Token Flow for Renewed Sessions

            The OAuth 2.0 refresh token flow renews access tokens issued by the OAuth 2.0 web server flow or the OAuth 2.0 user-agent flow.

            Required Editions

            Available in: both Salesforce Classic (not available in all orgs) and Lightning Experience
            Available in: All Editions

            After a client—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.

            The refresh token flow involves these steps.

            1. The connected app uses the existing refresh token to request a new access token.
            2. After verifying the request, Salesforce grants a new access token to the client.

            Request an Updated Access Token

            A connected app can use the refresh token to get a new access token by sending one of these refresh token POST requests 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=refresh_token&
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 as follows:

            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 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=refresh_token&
refresh_token=your token here
            Note
            Note If the client_id and client_secret are sent in the POST’s body, the authorization header is ignored.

            Avoid sending simultaneous requests that contain the same refresh token. If your client sends identical requests at the same time, some of the requests fail intermittently and the Status column in the Login History displays Failed: Token request is already being processed. Instead of continually sending requests for new access tokens, cache and reuse tokens instead. If you do send simultaneous requests with the same refresh token, which isn’t recommended, develop a way to retry the requests when this error occurs.

            With either refresh token POST request format, include these parameters.

            Important
            Important When developing OAuth integrations, always pass sensitive information in the body of a POST request or in a request header. Don't use GET parameters in the URL query string to pass sensitive information. Sensitive information includes but isn't limited to usernames, passwords, OAuth tokens, client secrets, and any personally identifiable information. For more information on security best practices, see Storing Sensitive Data in the Secure Coding Guide.
            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 refresh_token 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 client_assertion parameter.

            The value of client_assertion_type must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
            format

            If not included in the request’s header, you can specify the expected return format. The format parameter takes precedence over the request’s header. These formats are supported.

            • urlencoded
            • json (default)
            • xml

            Salesforce Grants a New Access Token

            After verifying the request, Salesforce sends a response with a new access token to the connected 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":"id api refresh_token"
}

            And here’s an example XML response.

            <Oauth>
   <access_token>00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNB
       aT1cyWk7TrqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4 
   </access_token>
   <token_type>Bearer
   </token_type>
   <scope>id api refresh_token
   </scope>
   <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%21AR8AQP0jITN80ESEsj5EbaZTFG0RNBaT1cyWk7TrqoDjoNIWQ2
ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4
&token_type=Bearer&scope=id%20api%20refresh_token
&instance_url=https%3A%2F%2FyourInstance.salesforce.com
&id=https://login.salesforce.com%2Fid%2F00Dx0000000BV7z%2F005x00000012Q9P
&issued_at=1278448101416
&signature=CMJ4l%2BCCaPQiKjoOEwEig9H4wqhpuLSk4J2urAe%2BfVg%3D

            If refresh token rotation is enabled for the connected app or external client app, the response includes a new refresh token. Here's an example JSON response if refresh token rotation is enabled.

            { 
"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNBaT1cyWk7T...",
"refresh_token":"CjAwRHgwMDAwMDAwQlY3eiFBUjhBUVAwaklUTjgwRVNFc2o1RWJhWl...",
"signature":"SSSbLO/gBhmmyNUvN18ODBDFYHzakxOMgqYtu+hDPsc=",
"scope":"id api refresh_token",
"instance_url":"https://yourInstance.salesforce.com/",
"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P"
"token_type":"Bearer",
"issued_at":"1278448384422",
}

            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.
            refresh_token A new refresh token. Use the refresh token to get a new access token the next time you invoke the refresh token flow. This parameter is included only if you enable refresh token rotation for your connected app or external client app.
            token_type A Bearer token type, which is used for all responses that include an access token.
            token_format

            If your connected app or external client app is enabled to issue JSON Web Token (JWT)-based access tokens, your response includes this parameter to indicate the format of the access token. The value is jwt.

            This parameter isn't included if your app issues opaque access tokens.
            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.

            See Also

             
            Loading
            Salesforce Help | Article