Salesforce: How to get the access token expires_at

Salesforce breaks with a common OAuth convention: Their token endpoint does not return the expires_at parameter, which indicates when the access token expires.

In this post we will show you how to retrieve the expiration date of Salesforce access tokens.

Problem: No expires_at in token response

A typical response from Salesforce’s access token endpoint looks like this:

{ 
	"access_token":"00Dx00...",
	"refresh_token":"CjA...",
	
	"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 problem: This response does not tell us how long the access token is valid.

Without knowing the expiration date we don’t know when we have to go and refresh the access token with the refresh token.

How to fetch expires_at

To get the expiration date of the Salesforce OAuth access token we need to make and additional API request to a token introspection endpoint.

This endpoint tells us, amongst other things, when the access token is set to expire.

Raw HTTP request:

POST /services/oauth2/introspect HTTP/1.1
Host: <salesforce instance URL>
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <client_id:client_secret as basic auth encoded>

token=<access_token>
token_type_hint=access_token
  

Or as a curl command:

curl -XPOST \
-H 'Authorization: Basic <client_id:client_secret as basic auth encoded>' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-d 'token=00DR00000009GVP!AR...&token_type_hint=access_token' \
'https://yourInstance.salesforce.com/services/oauth2/introspect'
  

The response for this request looks something like this:

{
	"active": true,
	"scope": "id api refresh_token",
	"username": "xxxx@yyyy.com",
	"exp": 1549921091,
	"iat": 1549917491,
	"sub": "xxxx@yyyy.com",
	"aud": "https://yourInstance.salesforce.com",
	"iss": "https://yourInstance.salesforce.com",
	"jti": "AT.pxxxxxxxxxxxxxxxxxxxxxxx",
	"token_type": "Bearer",
	"client_id": "xxxxxxxxxxxxxxxxxxxx",
	"uid": "00ugfxxxxxxxxxxxxxxx"
}
  

There are two timestamps in here with cryptic names:

• exp: The expiration date of the access token in unix timestamp format. This is the expires_at value.
• iat: The timestamp when the token was issued. Should match the issued_at parameter of the token response.

Refreshing the access token

You should refresh the Salesforce access token before it expires by using the refresh token from the token response.

We recommend refreshing the token a good bit before it expires: There are no penalties for this, but it minimizes the chance that your API requests fail due to an expired token.

Note that refreshes can also fail. We wrote a separate article on how to fix Salesforce refresh token errors.

Skip the hassle: Use Nango for Salesforce OAuth

Implementing Salesforce OAuth well is not trivial and can be time consuming.

Nango is an open-source solution for API authorization.

It has pre-built and battle tested implementations of the Salesforce OAuth flow and hundreds of other APIs.

It also handles:

• Automatic access token refreshes
• Keeping refresh tokens alive
• Secure token storage
• Detection of broken tokens

You can learn more about it on the Nango docs.