Setting up a Web Services API integration is a standard pattern: configure a Connected App on the Salesforce side, generate OAuth credentials, pick the right API for the workload, authenticate, and make calls with proper error handling. The pattern is the same for every external caller (Mulesoft, custom Node service, Python script, low-code platform), only the syntax changes. Walk through this once and the next integration is straightforward. The mistake most teams make is skipping the rate-limit analysis until the integration is in production and hitting daily caps.
- Create a Connected App with the right OAuth scopes
From Setup, App Manager, click New Connected App. Enter the integration name, contact email, and logo. Enable OAuth Settings. Set the Callback URL to the external system OAuth callback (or localhost for testing). Select the required OAuth Scopes: api for record access, refresh_token for long-lived sessions, openid for user identity, web for web-server flow. Save the Connected App. Salesforce generates a Consumer Key and Consumer Secret; copy them to your external system secret store. Configure IP restrictions or trusted IP ranges to limit where the credentials can be used from.
- Pick the right API and the right OAuth flow
Match the API to the workload using the rules of thumb above. Match the OAuth flow to the caller pattern. Web Server flow for human-initiated access. JWT Bearer flow for server-to-server with a certificate. Client Credentials flow (new) for server-to-server without user context. Username-Password flow is legacy and should be avoided. Refresh Token flow for long-lived sessions that survive token expiration. Document the API and flow choice in the integration runbook. The choice determines the credential rotation requirements and the error-handling logic the caller has to implement.
- Authenticate and make a smoke-test call
From the caller, perform the OAuth flow to obtain an Access Token. Make a smoke-test call against a known-good endpoint (typically /services/data/v59.0/sobjects/Account/describe). Confirm the response includes the expected fields and the status code is 200. If the call returns 401 Unauthorized, check the Access Token format, the OAuth scopes on the Connected App, and the user permissions. If the call returns 403, check IP restrictions and profile-level API access. Once the smoke test passes, move to the actual integration logic. Never deploy an integration that has not passed the smoke test in production conditions.
- Add monitoring, retries, and rate-limit handling
On the caller side, log every API call with timing and result. Watch for the daily API usage to climb toward the org limit; throttle proactively at 70 to 80 percent of the cap. On any 503 or 429 response, back off with exponential delay before retrying. On any token expiration (401 after the token was valid), refresh the token and retry. Add the integration to the org API monitoring dashboard so the admin team can see traffic from each caller. Document the rate-limit budget for each caller in the integration runbook so future architects know which budget belongs to which workload.
- Username-Password OAuth flow is being phased out for security reasons. New integrations should use JWT Bearer or Client Credentials. Legacy callers using Username-Password will fail when Salesforce disables the flow.
- API calls without a version number default to the oldest still-supported version. This behavior is rarely what you want; always include the version in the URL path.
- Bulk API uses different rate-limit accounting than REST. A Bulk job uses fewer API calls per record but blocks behind a queue. Picking the wrong API for the workload causes rate-limit errors at scale.
- Connected App Consumer Secrets do not auto-rotate. If a secret leaks, you have to manually regenerate it in Setup and update every caller. Plan rotation as a recurring task.
- Daily API Request Limit is shared across the entire org. One runaway integration can lock out every other caller for the rest of the day. Add per-caller monitoring and throttling to prevent this.