When do Salesforce access tokens expire?

Jan 21, 2021

Learn how to retrieve the expiration for Salesforce access tokens and the typical expiry period

If you're building a Salesforce integration into your app, particularly a "Connected App" style of integration, and your integration uses OAuth to get access to Salesforce's REST APIs, you may be wondering when the access tokens issued by Salesforce expire.

According to the OAuth 2.0 spec the expires_in parameter is included with the Access Token response and provides the lifetime of the returned token in seconds. And while this parameter is extremely common in OAuth implementations, it is merely recommended and not required. The Salesforce OAuth implementation does not use this parameter.

Typical Token Expiration

In our experience at Xkit, Salesforce Access Tokens typically expire in 2 hours (7,200 seconds), but this value is not guaranteed to be static—Salesforce could change it at any time with no warning.

Salesforce Access Tokens typically expire in 2 hours

How to determine token expiration

So what do you do? You have two options:

  1. Use your access token until you receive a 401 HTTP status code, and only refresh it then
  2. Use Salesforce's token introspection endpoint to determine when the token expires

Token Introspection

That's right! While Salesforce does not include an expires_in parameter, they do have a special token introspection endpoint as part of the extension to the OAuth 2.0 spec. This endpoint (Salesforce docs here) returns a JSON object that includes an exp property. This exp corresponds to the exp claim of the JWT spec. Unlike the expires_in parameter, exp is a Unix epoch timestamp.

Here's an example request from the Salesforce docs:

POST /services/oauth2/introspect HTTP/1.1
Host: https://mycompany.my.salesforce.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic M01WRzlsS2NQb05JTlZCSVBKamR3MUo5TExNODJIbkZWVlgxOUtZMQp1QTVtdTBRc


And an example response from our own experience:

HTTP/1.1 200 OK
Content-Type: application/json

{"active":true,"scope":"api refresh_token openid","client_id":"3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE","username":"user@example.com\",\"sub\":\"https://login.salesforce.com/id/000000000000000000/000000000000000000\",\"token_type\":\"access_token\",\"exp\":1610509606,\"iat\":1610502406,\"nbf\":1610502406}


So if you need to know when your Salesforce Access Token expires, call the introspection endpoint and you can figure it out for yourself. And don't forget to add the special refresh_token scope so you can refresh your access when it does expire.

Of course, if you want to avoid building (or heck, even learning) all that, you can use Xkit's Universal CRM integration framework to build integrations that work across CRMs without ever worrying about access tokens.

Building CRM integrations?

Xkit delivers deep integrations for every CRM with one build.

Get access ▶