What changes after refresh
The exact result depends on the sandbox type, refresh process, org configuration, and the app’s packaging or deployment model. Recheck rather than assuming that production configuration was copied perfectly. Pay particular attention to:
Keep the production and sandbox connection records separate. A token is not a portable environment switch.
| Area | Post-refresh check |
|---|
| Host | Sandbox login URL and My Domain URL |
| OAuth client | Client ID, policy, callback, and scopes |
| Installation | Connected App or External Client App access |
| Users | Integration user, profile, permission sets, active status |
| Licenses | Required app or feature licenses |
| Data | Test records, record types, and external IDs |
| Secrets | Sandbox token and refresh-token records |
Check the host first
The authorization request must use the intended Salesforce host. Production commonly uses `login.salesforce.com` or a My Domain host; a sandbox may use `test.salesforce.com` or its sandbox My Domain. The token’s returned instance URL must then be used for API calls.
Example authorization shape:
Do not hard-code the production host in a sandbox connector. Log the environment alias and host, but never log tokens or authorization codes.
https://test.salesforce.com/services/oauth2/authorize
?response_type=code
&client_id=CLIENT_ID
&redirect_uri=REDIRECT_URI
&code_challenge=CHALLENGE
&code_challenge_method=S256
Verify the app and its policy
Open the sandbox Setup area and inspect the relevant OAuth client. Confirm the client ID in the request belongs to that environment and that the app is available to the integration user. Review permitted-user policy, scopes, callback URL, PKCE requirement, and any admin approval controls.
Salesforce’s current platform direction also distinguishes existing Connected Apps from newer External Client Apps. If your organization is creating a new client after the Spring ’26 change, confirm which app type the org supports instead of assuming the old Connected App workflow is available.
If the app is blocked, uninstalled, or awaiting approval, correct that state through the administrator’s security process. Do not tell a user to approve an unknown client merely because the sandbox is under time pressure.
Recheck users and licenses
The integration user may be inactive, have a changed profile, lack a permission set, or no longer have access to the required object. Sandbox refreshes can also expose differences in licenses and managed-package access. If your post-refresh runbook uses Match Production Licenses, complete it before testing application behavior and record which licenses were intentionally matched.
A successful OAuth token proves that authorization completed; it does not prove the user can read or write the target object. Follow the token exchange with a harmless API read using the returned instance URL.
Callback URLs and PKCE
Redirect URIs are exact. Check scheme, host, path, port, and trailing slash. Staging and sandbox callbacks should be separate from production values. If PKCE is required by the app policy, generate a verifier and challenge for each authorization attempt, store the verifier with state, and send the original verifier during token exchange.
A refresh can reveal a session-store problem that was hidden in production. Test two browser tabs and multiple application instances. The callback must retrieve the verifier belonging to its own state value; a single overwritten session variable can create a false impression that Salesforce OAuth is broken.
Clean recovery sequence
First revoke failed test sessions. Confirm host and client ID. Verify app access, user status, licenses, callback, scopes, and PKCE policy. Start a fresh browser authorization, exchange the code once, store the sandbox tokens separately, and call the returned instance URL. Then test the exact object operation the integration needs.
If the API returns 403, investigate object or field permissions. If authorization fails before consent, investigate app approval or policy. If the callback fails, investigate state, redirect URI, and shared session storage. If refresh fails, inspect refresh-token lifetime, client identity, and revocation state.
Prevent the next refresh incident
Keep a post-refresh checklist in source control. It should include environment host, client ID, app type, callback URLs, permitted-user policy, PKCE setting, integration user, licenses, scopes, test record, and owner. Automate read-only checks where possible, but require an administrator for security and license changes.
Use environment-specific secret aliases and refuse to start a sandbox worker with a production credential. Store a redacted last-known-good configuration. Run an OAuth smoke test after every refresh and before handing the sandbox to developers.
The smoke test should be reproducible: record the environment, test user, client ID fingerprint, callback alias, API version, target object, and expected result. It must not store the authorization code, access token, refresh token, or PKCE verifier. If the test fails, classify the failure by stage so developers do not change application code when the sandbox merely needs an administrator to restore app access.
If the sandbox is shared by several teams, publish the refresh date and freeze application changes until the smoke test passes. Otherwise a client-side change and a post-refresh configuration issue can arrive together and make the incident much harder to isolate. Keep a named owner for the refresh checklist and a second reviewer for the first successful authorization. This catches wrong-host and wrong-client mistakes before developers begin using the refreshed sandbox.
Keep a named owner for the refresh checklist and a second reviewer for the first successful authorization. This catches wrong-host and wrong-client mistakes before developers begin using the refreshed sandbox. Record the test result and refresh date so a later failure can be compared with the last known-good environment.
The trap: testing only the login screen. OAuth may succeed while the returned instance URL, user permissions, license access, or target object operation is still wrong.
Make the post-refresh test reproducible
Record the sandbox refresh date, host, client ID fingerprint, app type, test user, callback alias, API version, target object, and expected result. Do not store tokens or authorization codes. A second reviewer should run one fresh authorization and one API read before developers resume work. This creates a clean boundary between a refresh configuration issue and a later code change.
Where these facts come from
