As the title suggests, we use Named Credentials to connect to a external service, that service returns an access token we can use for a period of time. I wanted to know if there was some built in function to cache that token for x hours or do we need to build this using Apex?

1 Answer 1


When using OAuth, the Named Credentials automatically stores the Access Token and Refresh Token. When making a callout using Named Credentials, Apex will automatically try the Access Token first, and if it gets a 401, with an error response of invalid_token, it will try the Refresh Token to get a new Access Token, and try again, and if that fails, then throws the appropriate error. This all happens behind the scenes without any effort on part of the developer.

For non OAuth tokens, such as API keys or something else, you need to arrange for your own storage. This could be a custom setting, custom metadata, platform cache, or another solution. You'll need to remember to keep this information secure by access controls and/or encrypting the token.

  • This is most useful. Is the behavior around requiring a 403 described above documented anywhere? At the moment the service I'm calling is returning 401 (and a json error showing that the JWT token is expired). I need some documentation to convince the API owner to change the status code as described.
    – Dan
    Nov 25, 2021 at 16:24
  • @Dan I believe I may have been in error. This KB article states that a refresh token can only be obtained from a 401 response, and the IETF Bearer specification supports that statement. As such, I think your situation is where the status is correct, but the response is somehow wrong. The response must be invalid_token with a status code 401 to trigger a response.
    – sfdcfox
    Nov 25, 2021 at 19:06
  • @Dan Also note that if there is no refresh token (e.g. it is a JWT), then an automatic refresh isn't possible. JWT does not provide a refresh token, so no automatic refresh is possible.
    – sfdcfox
    Nov 25, 2021 at 19:08
  • 1
    Thanks @sfdcfox if the token refresh is not automatic, what triggers Salesforce to refresh the bearer token? it is expiring every 3599 seconds and the next callout after that typically fails. I would expect (if the API being called implements the authentication correctly, as described in the IETF Bearer specification) that Salesforce would refresh the token and re-request the resource, without pushing that responsibility down to the apex/implementation code?
    – Dan
    Nov 26, 2021 at 14:43
  • @Dan Yes, the token refresh should happen automatically and transparently to the Apex code making the callout. This assumes that (a) a Refresh Token endpoint is set on the Named Credential, (b) the Refresh Token has been returned in the initial OAuth flow, and (c) the Refresh Token is still valid. Maybe the Refresh Token is expiring? Maybe the wrong "scope" was used? I've seen this used successfully "in the wild", so I know it can be done.
    – sfdcfox
    Nov 26, 2021 at 15:32

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .