Client App
A Client App in Salesforce is any external software application that authenticates against an org and uses the platform APIs to read or write data.
Definition
A Client App in Salesforce is any external software application that authenticates against an org and uses the platform APIs to read or write data. The category covers mobile apps (the Salesforce mobile app, custom apps on the Mobile SDK, third-party iOS and Android apps), web apps (custom portals, partner integrations), backend services (ETL pipelines, billing systems, data warehouses), and command-line tools like the Salesforce CLI. Each client app is registered in the org through a definition record that carries its OAuth consumer key, allowed scopes, callback URL, and security policies.
There are two registration frameworks for that record. The older one is the Connected App. The newer one, which Salesforce now recommends in every situation, is the External Client App (ECA). Starting in Spring '26, new Connected Apps can no longer be created through the UI or API without a support request, so any fresh client app you stand up today should be an External Client App. Understanding the client app concept is foundational to anything beyond the standard Salesforce UI, because every external system that touches your data is one.
How client apps register, authenticate, and stay governed
The registration record behind every client app
A client app cannot call Salesforce APIs anonymously. It first needs a definition record in the target org, created under Setup in App Manager. That record holds the OAuth consumer key and secret, the callback (redirect) URL, the list of allowed OAuth scopes, the refresh token policy, IP relaxation rules, and session timeout settings. When the app requests a token, Salesforce checks the incoming credentials against this record before issuing one. For years that record was a Connected App. The current framework is the External Client App, which stores the same information but splits it across two metadata files. A global settings file holds the consumer secret and never gets packaged. A local settings file references the global one and carries no secrets, so it can travel safely into a second-generation managed package. This separation is the structural reason Salesforce built ECAs: it keeps sensitive credentials out of distributed metadata while keeping the integration itself portable across orgs.
Connected App and External Client App: the same job, different generation
Both frameworks do the same thing. They let a third-party application integrate using OAuth 2.0 and SAML 2.0. The difference is generation and lifecycle. Salesforce calls External Client Apps the next generation of Connected Apps. They are fully metadata-compliant, they keep developer and admin roles separate, and they were designed for 2GP packaging from the start. The official guidance is plain: use external client apps in all situations, and migrate existing local connected apps to local external client apps. The deprecation has teeth. As of Spring '26, customers cannot create new Connected Apps through Setup or the Metadata API unless they ask Salesforce Support to re-enable it, and a future release removes even that escape hatch. Existing Connected Apps keep working, and an End-of-Support date is expected but not yet published. A handful of features still live only on Connected Apps, including 1GP packaging, user provisioning, and automatic copy into cloned sandboxes, so check those before you migrate a specific app.
Picking the right OAuth flow for the client app type
Different client app types call for different OAuth flows, and the framework you pick has to support the flow you need. A server-rendered web app uses the OAuth 2.0 web server flow (authorization code). A mobile or single-page app adds PKCE to that flow to protect the code exchange on a public client. A pure server-to-server integration with no human in the loop uses the JWT bearer flow or the client credentials flow, both of which authenticate as a single named identity. Devices without a browser use the device flow. External Client Apps support the web server, client credentials, JWT bearer, device, token exchange, and code-and-credentials flows. They deliberately do not support the legacy OAuth username-password flow. That is the single biggest gotcha when migrating: any Connected App that authenticated by posting a username and password stops working as an ECA, and you have to re-architect it onto the web server flow with PKCE or onto client credentials before you move it.
Scopes decide what the client app is allowed to ask for
OAuth scopes are the permissions a client app requests when it authenticates. Common ones are api for REST and SOAP calls, refresh_token for long-lived sessions that survive without re-prompting a user, web for browser-based access, and full for everything. Scopes are the first half of the access equation. They cap what the app can ever request. The second half is the running user. Even a client app holding the api scope can only see and change the records that the authenticated user is allowed to see and change, filtered through that user profile, permission sets, sharing rules, and field-level security. This two-layer model is why a dedicated integration user matters so much. Pair a narrowly scoped client app with an integration user that has only the permission sets the integration genuinely needs, and the blast radius of a leaked token stays small. Request only the scopes the app uses; over-scoped client apps are a recurring finding in every Salesforce Security Review.
Locking down where and how the client app connects
A client app registration is also where you set the security floor for the integration. IP relaxation policy controls whether tokens are bound to a range of trusted addresses. For a backend service that always runs from a known data center or NAT gateway, enforcing an IP allowlist means a stolen refresh token is useless from anywhere else. Session policies control how long an issued session stays valid and whether high-assurance sessions are required. Refresh token policy decides whether refresh tokens expire, expire on inactivity, or live until revoked. Defaults are permissive enough to make development frictionless, which is exactly why they are rarely safe for production. A mature program treats every new client app as a small access-control decision: which identity, which scopes, which IP range, which session lifetime. The same Setup record that registers the app is where all four of those controls live, so there is no excuse to leave them at default once the integration goes live.
Mobile and packaged client apps
Custom mobile apps built on the Salesforce Mobile SDK are client apps too. The SDK handles the OAuth dance and refresh-token storage on the device, but the app still needs a registration record in the org with its consumer key and callback URL. Most enterprise customers run at least one custom mobile client app for field service, employee self-service, or a customer-facing flow. The packaging story is where External Client Apps pull ahead. Because the consumer secret lives in a separate global settings file that is never packaged, an ISV can ship the app as a 2GP managed package and let each subscriber org generate its own OAuth settings on install. That is cleaner than the Connected App model, where packaged credentials and subscriber configuration were harder to keep apart. If you build software for the AppExchange, External Client Apps are the framework that fits modern second-generation packaging. If you maintain an older 1GP package, note that 1GP distribution is still a Connected-App-only capability for now.
Auditing, rotating, and migrating client apps
Production orgs accumulate client apps. A mature org often has dozens, one for every external system that touches the data. Treat them as a governed inventory, not a set-and-forget list. Run an audit at least annually: list the registered apps, confirm each one still maps to a live integration, verify its scopes still match what the integration does, and rotate the consumer secret. Long-unrotated secrets are the most common breach path, because keys leak through old code repositories, CI logs, and retired developer machines. When you migrate a Connected App to an External Client App, App Manager offers an automated path that builds the ECA from the existing record, and the old Connected App stays in App Manager as a read-only copy. Migration can fail for specific reasons worth knowing in advance: an expired P12 certificate used for Apple push notifications, a deprecated Android server key, or reliance on the username-password flow. Clear those first, then migrate, then point the integration at the new app and retire the old one.
Create an External Client App for an API integration
Stand up a new client app the modern way by creating an External Client App. This replaces the legacy Connected App flow, which Salesforce is disabling for new apps in Spring '26. The steps below register a local ECA for an API integration.
- Open App Manager
In Setup, enter App Manager in the Quick Find box and open it. Click New External Client App in the top right. If you only see New Connected App, your org may need External Client Apps enabled first under External Client App Settings.
- Fill in the basic details
Give the app a name, an API name, and a contact email. Set the distribution state to Local for a single-org integration. Save to create the record before configuring OAuth.
- Enable and configure OAuth
On the app, edit the OAuth settings, select Enable OAuth, and enter a secure HTTPS callback URL. Choose the OAuth flow you need, such as the web server flow with PKCE for a user-facing app or client credentials for server-to-server.
- Select scopes and policies
Add only the OAuth scopes the integration actually uses, such as api and refresh_token. Set the refresh token policy, IP relaxation, and session timeout to match your security requirements rather than leaving defaults.
- Capture the consumer key and test
After saving, retrieve the consumer key and secret from the app. Use them in your client to request a token against the org login endpoint, and confirm the returned access token can call the API.
The human-readable label for the app, shown in App Manager and in the user OAuth approval screen.
The unique developer name used in metadata and packaging; it cannot be changed casually after creation.
The address Salesforce uses to reach the app owner about the integration.
The secure HTTPS endpoint where Salesforce redirects after authorization; required once OAuth is enabled.
The permissions the app may request at authentication time, such as api or refresh_token.
- External Client Apps do not support the OAuth username-password flow. If your integration relied on it, move to the web server flow with PKCE or client credentials before building the app.
- Use an HTTPS callback URL. Salesforce rejects insecure http endpoints because the authorization exchange carries sensitive tokens.
- Request the narrowest set of scopes that works. An over-scoped app is flagged in Security Reviews and widens the impact of a leaked token.
- Pair the app with a dedicated integration user, not an admin. Scopes cap what the app can request, but the running user decides what it can actually touch.
Prefer this walkthrough as its own page? How to Client App in Salesforce, step by step
Trust & references
Cross-checked against the following references.
- External Client Apps and Connected AppsSalesforce
- External Client AppsSalesforce
Straight from the source - Salesforce's reference material on Client App.
Hands-on resources to go deeper on Client App.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Client App in Salesforce platform terms?
Q2. What protocol does a Client App use to authenticate against Salesforce?
Q3. What is a common Client App scenario in real-world Salesforce work?
Discussion
Loading discussion…