Before you create anything
Write down the client type, target orgs, user population, data actions, callback URLs, token storage, and revocation plan. A one-company internal tool and a multi-customer SaaS product need different boundaries.
Use a separate app or configuration for sandbox testing where practical. Record the production and sandbox login hosts. Never solve an environment mismatch by reusing a production token in a sandbox.
Callback URLs are exact
https://app.example.com/oauth/callback and https://app.example.com/oauth/callback/ are different values. Production and staging hosts are different. A mismatch may appear as a redirect or approval error rather than a helpful configuration message.
Use an allowlist in your application and compare the callback returned by the request with the one registered in Salesforce. Do not accept an arbitrary redirect URI from a query parameter.
Choose scopes deliberately
Request only what the application needs. A reporting tool may need API read access; a sync tool may need read and write access; a UI session may require additional scopes. Larger scopes increase the impact of a compromised token and can make an administrator less willing to approve the app.
Test the smallest scope set first. A missing scope should produce a clear reconnect or admin message, not an infinite retry loop.
Choose who may authorize
Salesforce documents “All users may self-authorize” and “Admin approved users are pre-authorized” as different policies. The second requires profile or permission-set access. If you switch from self-authorization to admin approval, existing users can lose access unless their authorization is explicitly granted.
Use admin approval when the organization wants a controlled allowlist. Use self-authorization only when the app and consent experience are trusted and the business accepts user-level approval.
Implement authorization code flow
The browser step sends the user to /services/oauth2/authorize with response_type=code, client_id, redirect_uri, and requested scopes. If PKCE is required, add a code_challenge and code_challenge_method=S256. Store state and the verifier server-side.
The callback validates state, checks the returned error, and sends the code to /services/oauth2/token with grant_type=authorization_code, client_id, redirect_uri, and code_verifier when PKCE is used. Add the client secret only when the configured flow requires it.
Never exchange the code in browser JavaScript if the client secret or token must remain confidential. Do not log authorization codes, verifiers, secrets, or access tokens.
Test access in the target org
Run a fresh authorization for an administrator and an ordinary intended user. Test allowed and denied users, revoked sessions, expired access tokens, refresh, and a request against the correct instance URL. Verify that the API call is made to the returned instance rather than always to the login host.
Check Connected Apps OAuth Usage for the session. Salesforce provides controls to install, uninstall, block, revoke, and review app usage. These controls are part of the operational runbook.
Common setup failures
A generic approval error can mean the app is uninstalled or blocked. A missing code_challenge means PKCE is required but absent. An invalid redirect URI means the registered value differs from the request. A successful login followed by an API 403 usually points to scopes, user permissions, or object access rather than OAuth syntax.
Treat each class differently and preserve the exact time and org in diagnostics. A single vague “Salesforce auth failed” message wastes the administrator’s time.
Production checklist
Use HTTPS. Keep secrets in a secret manager. Encrypt refresh tokens. Rotate client secrets according to policy. Provide reconnect and revoke controls. Monitor failed exchanges and unusual token use. Separate tenant records. Keep a redacted release fixture for each environment. Review scopes when features change.
If a new Salesforce release changes policy, test before the release window rather than waiting for all users to fail simultaneously.
The trap: testing only the admin user in a sandbox. Production policy, record access, callback URLs, and PKCE settings can differ.
Create a release test matrix
Test one administrator and one ordinary user in each environment. Test a new connection, a reconnect after revocation, an expired access token, a refresh, an unavailable scope, a blocked app, and a callback mismatch. Confirm that every failure gives the operator a useful next action.
Run an API read against the instance URL returned by Salesforce and verify that the object permission is real. Authentication proves who the client is; it does not automatically grant access to every object, field, or record.
Keep setup metadata under change control: app identifier, callback URLs, scopes, permitted-user policy, refresh-token policy, and PKCE setting. Compare the current org configuration with the last known-good snapshot during incidents.
Plan for revocation
Provide an admin procedure to revoke app sessions, rotate a client secret, disable a tenant connection, and reconnect. State what queued work is safe to replay and what needs review.
Test the procedure in a sandbox with realistic permissions before publishing it. Include screenshots or exact Setup search terms, but do not include secrets. A runbook is successful when a second administrator can restore one test connection without asking the original developer which setting was changed.
Connected App or External Client App?
For a new Salesforce integration in 2026, check whether the org expects an External Client App. Existing Connected Apps can continue to matter, but the platform has restricted creation of new legacy Connected Apps. Put the app type, client ID, callback URLs, scopes, permitted-user policy, and PKCE setting in the release record so a future administrator does not recreate the wrong client type.
Where these facts come from
