Why does my Salesforce integration work for weeks then suddenly break?

Refresh token expiry. The classic signature is: integration is provisioned, runs cleanly for 30, 60, 90, or 720 days, and then in a single instant every call starts returning INVALID_SESSION_ID. The Refresh Token Policy on the ConnectedApp determines the window — anything other than 'Refresh token is valid until revoked' produces this exact failure pattern. Fix: Setup → App Manager → [your app] → Manage → Edit Policies → set Refresh Token Policy to 'Refresh token is valid until revoked', save, then re-authorize the integration so it gets a new refresh token under the new policy. The old token doesn't auto-upgrade; you have to repeat the OAuth flow.

What does INVALID_SESSION_ID actually mean and how do I distinguish it from other auth errors?

INVALID_SESSION_ID specifically means the access token Salesforce received is no longer valid — either it expired (session timeout), the user logged out, the user was deactivated, or an admin manually revoked the token in Setup → Connected Apps OAuth Usage. It's NOT the same as invalid_grant (refresh failure) or invalid_client (wrong consumer key). The correct response from your integration: catch INVALID_SESSION_ID, request a new access token using your refresh token, retry the original call once. If you get invalid_grant on the refresh, the refresh token itself is dead — that's when you need to repeat the full OAuth authorization flow.

How long should I set the Salesforce session timeout for server-to-server integrations?

Set the ConnectedApp's Session Timeout to 'None' and rely on refresh tokens for long-running work. 'None' here means 'don't impose an additional timeout beyond the org-level session policy' — it's not 'tokens never expire' (Salesforce access tokens always expire; refresh tokens are how you get new ones). For user-interactive sessions (someone logged into the app), shorter timeouts (15 min - 2 hours) are appropriate for security. For server integrations doing scheduled work, the shorter the access-token lifetime the more refresh round-trips you make for no security benefit.

What happens to all my tokens if I deactivate the integration user?

Every access token and refresh token issued to that user is immediately invalidated. Salesforce doesn't wait for the next API call to revoke; the revocation is real-time. Every integration the deactivated user had authorized — across every ConnectedApp in every org they were a member of — breaks simultaneously, usually within seconds. The fix is to repeat the OAuth flow with a different active user. The defensive pattern is to have a dedicated 'API integration' user that never gets touched as part of HR offboarding — name it `integrations@yourcompany.com` or similar so it's obviously not a real human.

Should I migrate my ConnectedApp to an External Client App (ECA) now?

Yes, eventually — and the timeline is tighter than most teams realize. Salesforce notified customers in May 2026 that SOAP `login()` (the username + password + security token method) retires in Summer '27, with API versions 65+ already dropping it. Spring '26 blocked new ConnectedApp creation in newly-created orgs. Existing ConnectedApps continue to work, but new customer onboardings can't use them. The replacement is the External Client App framework, which uses a 2GP packaged install on each customer org. For BuildForce's customers we ship dual-mode auth (ConnectedApp + ECA) and a one-click migration banner; if you maintain your own integrations, start the ECA migration before the Summer '27 deadline becomes urgent.

How can I tell when a refresh token is about to expire?

Salesforce doesn't surface the refresh token's expiration date in the UI or in the OAuth response. The only way to know is to either (a) record the issued-at time when you complete the OAuth flow and add your ConnectedApp's policy duration to it, or (b) periodically attempt a refresh and catch invalid_grant. Most monitoring tools (BuildForce included) take approach (a) — track every ConnectedApp's policy and issued-at timestamp, alert 48 hours before the calculated expiry. The downside: if someone manually revokes a token in Setup, you won't know until the next refresh attempt fails. That's why you also need a 401-handling retry path in the integration itself.

What's the right way to handle OAuth token refresh from a serverless function?

The challenge in serverless is that you can't keep an access token in memory between invocations, so naive implementations refresh on every cold start (expensive and noisy). The right pattern is: store the refresh token + last issued access token + issued-at timestamp in a shared store (Redis, Supabase, KV). On invocation, check if the access token is still within its lifetime; if yes, use it; if no, refresh and update the store atomically. Implement a mutex or use 'check-and-set' semantics in your store so two concurrent invocations don't both try to refresh and race each other. Salesforce will accept multiple parallel refresh requests, but you'll burn refresh tokens unnecessarily and may hit rate limits.

Fix Guide

How to Fix Salesforce OAuth Token Refresh Failures

Step-by-step fix guide with AI-powered diagnosis from BuildForce.

Salesforce OAuth refresh failures show up as INVALID_SESSION_ID or 'session expired' errors on integrations that worked yesterday. There are four common causes, in roughly the order you should check them: (1) the ConnectedApp's Refresh Token Policy is set to a fixed window (30/60/90 days) instead of 'until revoked' — the integration runs fine for that window and then dies in a single instant; (2) the user who originally authorized the integration was deactivated, immediately invalidating every token issued to them; (3) the ConnectedApp's IP Relaxation policy is 'Enforce IP restrictions' and your integration server's IP isn't whitelisted; or (4) session timeout is inherited from an org-level policy short enough to expire access tokens between calls. The fix lives in Setup → App Manager → [your app] → Edit Policies. Set Refresh Token Policy to 'Refresh token is valid until revoked', IP Relaxation to 'Relax IP restrictions', and Session Timeout to 'None'. Then proactively refresh access tokens every ~90 minutes from your integration rather than waiting for a 401.

Session TimeoutRefresh Token PolicyUser DeactivationIP Relaxation

Get AI-Powered Diagnosis See Pricing

The classic OAuth refresh failure runs for weeks then dies in a single instant — which is exactly what makes it expensive. Nothing in your logs predicts the failure because the integration is genuinely healthy until the moment the refresh token hits the policy expiration. You don't get a 7-day warning. The 89-day-old integration looks identical to the 1-day-old one until day 90 at 00:00:01 UTC, when every API call starts returning 401.

It hits hardest on integrations built before Salesforce changed the ConnectedApp defaults in Spring '21. Anything provisioned earlier than that often inherited the old 'refresh token expires in 90 days' default, and unless someone explicitly went into the app's policies and changed it, the integration carries that policy forever. We've seen 5-year-old SOAP integrations break suddenly because nobody had touched the ConnectedApp settings the whole time — the original policy was still in effect.

Note (June 2026): Salesforce notified customers that SOAP `login()` retires in Summer '27 and Spring '26 already blocks new ConnectedApp creation. If your integration still uses username + password against SOAP, you're on a hard deprecation path independent of refresh-token policy. The replacement is the External Client App (ECA) framework, which uses OAuth + a packaged 2GP install. Migrate before you have to.

Salesforce ConnectedApp default Refresh Token Policy as of Spring '26: 'Refresh token is valid until revoked' is now the recommended default — but pre-Spring '21 apps usually inherited 'Expires after 30/60/90 days' and require an explicit policy update.

Source: Salesforce Help — Connected App OAuth Policies, Spring '26 release notes

Symptoms

Integration logs showing INVALID_SESSION_ID errors at regular intervals

Integrations working intermittently — failing then recovering after re-authentication

Scheduled jobs failing with 'Authentication failure' after running successfully for weeks

Connected apps requiring manual re-authentication every few hours or days

Bulk sync jobs starting then stopping mid-run with session errors

Root Causes

Connected app session timeout too short

By default, Salesforce connected apps inherit the org's session timeout (typically 2 hours). For server-to-server integrations, this means the access token expires every 2 hours requiring a refresh. If the refresh token is also limited, the integration breaks entirely.

Refresh token policy not set to 'until revoked'

The default connected app policy expires refresh tokens after a set period. For long-running integrations, the policy must be set to 'Refresh token is valid until revoked' to prevent periodic authentication failures.

Authorizing user deactivated

When the Salesforce user who authorized an integration is deactivated, all tokens issued to that user are immediately revoked. Integrations stop working with no warning.

IP relaxation policy forcing re-auth

If the connected app's IP relaxation is set to 'Enforce IP restrictions' and your integration server's IP isn't in the org's trusted IP ranges, every access attempt triggers a re-authentication challenge.

How to Fix It — Step by Step

Check the connected app OAuth policy

In Setup → App Manager, find your connected app and click Edit. Under OAuth Policies, set 'Refresh Token Policy' to 'Refresh token is valid until revoked'. Set 'Session Timeout' to the longest available option or 'None'.

Set IP relaxation to 'Relax IP restrictions'

In the same OAuth Policies section, set 'IP Relaxation' to 'Relax IP restrictions'. This is required for server-to-server integrations where the calling server's IP isn't in Salesforce's trusted IP list.

Verify the authorizing user is active

Check whether the Salesforce user who originally authorized the integration is still active. In Setup → Users, search for the integration user account. If deactivated, reactivate it or re-authorize using an active user.

Example

SELECT Id, Name, IsActive, LastLoginDate FROM User WHERE Id = '[integration_user_id]'

Re-authorize the connected app

After updating OAuth policies, revoke existing tokens and re-authorize the integration. In your integration platform, remove the Salesforce connection and re-authenticate. The new tokens will have the updated expiration policy.

Implement proactive token refresh

Configure your integration to proactively refresh access tokens every 90 minutes rather than waiting for a 401 response. This prevents mid-run authentication failures in long-running jobs.

Example

POST https://login.salesforce.com/services/oauth2/token
grant_type=refresh_token
&client_id={consumer_key}
&client_secret={consumer_secret}
&refresh_token={refresh_token}

Set up token health monitoring

Use BuildForce's token lifecycle monitoring to track all connected app token expiry dates and receive alerts 48 hours before tokens are scheduled to expire or be revoked.

Real-world incidents we've seen

A revenue-ops team whose Marketo→Salesforce sync had run flawlessly for 22 months stopped at 04:00 UTC on a Tuesday. Root cause: the ConnectedApp was provisioned in 2024 with a 720-day refresh-token policy. Day 720 was that Tuesday. They didn't have the original admin around to know what to look for; spent ~6 hours triaging the wrong layer (Marketo connector logs) before someone checked the Salesforce App Manager.
An IT consultancy lost OAuth for 14 customer-facing integrations in a single morning when a former contractor's Salesforce user was deactivated as part of an offboarding cleanup. Every integration he had originally authorized — across 14 different ConnectedApps in 6 different orgs — broke simultaneously. The fix required re-authorizing each one with a 'service' user instead of a real human's account.
A B2B SaaS startup's nightly data warehouse ETL stopped working after they migrated their integration servers to AWS — the Salesforce ConnectedApp had IP Relaxation set to 'Enforce', and the new EC2 IPs weren't in the trusted ranges. Symptoms looked like an auth bug; root cause was an IP policy. 'Relax IP restrictions' immediately resolved it.