Salesforce API access — External Client Apps vs connected apps, which OAuth flow to use, scopes (including the Agent API's), and the flows being retired
How an app or agent gets a Salesforce token in 2026 — External Client Apps as the default now that new connected apps are restricted (since Spring '26), the flows to choose (client credentials, JWT bearer, web server with PKCE, refresh token), the OAuth username-password flow retiring on February 20, 2027 and SOAP login() in Summer '27, the scopes the Agent API needs, the Run As user, and the ECA metadata types for deploying the app as source.
markdownreferencev19YVT-2ZYJstage: designtrust: officialservice: authinterface: portalinterface: cliExternal Client AppECAExternal Client App Managerconnected app creation restricted Spring '26Connected apps creation is restrictedApprove Uninstalled Connected Appsclient credentials flowEnable Client Credentials FlowRun As userJWT bearer flowEnable JWT Bearer FlowUse digital signaturesAdmin approved users are pre-authorizedweb server flow PKCErefresh token flowrefresh token policyOAuth username-password flow retirement February 20 2027grant_type=passwordSOAP login() retirementscopes api refresh_token offline_access webchatbot_apisfap_apiIssue JWT-based access tokens for named usersapi_instance_urlconsumer key and secretsf org login jwtsf org login web--client-idExternalClientApplicationExtlClntAppOauthSettingsExtlClntAppGlobalOauthSettingsExtlClntAppOauthConfigurablePoliciesOauthCustomScope
Salesforce API access
External Client Apps first
Connected apps creation is restricted as of Spring '26. Existing connected apps keep working. Creating new ones needs Salesforce Support and the Approve Uninstalled Connected Apps permission. Salesforce recommends External Client Apps (ECAs), which it describes as designed to improve security and fix connected apps' packaging and distribution problems.
The one place you still need a connected app: a Dev Hub that creates scratch orgs or sandboxes with the CLI. sf org login jwt needs your own ECA (or connected app). sf org login web uses Salesforce's built-in app unless you pass --client-id.
As source, an ECA is ExternalClientApplication (folder externalClientApps, suffix .eca), plus settings types such as ExtlClntAppOauthSettings, ExtlClntAppGlobalOauthSettings and ExtlClntAppOauthConfigurablePolicies. The consumer key and secret are read in Setup (External Client App Manager → Settings → OAuth Settings → Consumer Key and Secret, after an email code), and never belong in source. The files, and how to retrieve an app's policies: reference/auth/external-client-app-as-source.md.
Which flow
| Flow | Use it for | Set up on the ECA |
|---|---|---|
| Client credentials | Server-to-server, middleware, scheduled jobs, the Agent API | Enable Client Credentials Flow; on the Policies tab set Run As (Username). Calls run as that user. Token requests must go to the My Domain URL. No refresh token is issued |
| JWT bearer | Server-to-server and CI, with a certificate instead of a secret; sf org login jwt | Enable JWT Bearer Flow, upload the certificate, Permitted Users = Admin approved users are pre-authorized, and pre-authorize the user's profile or permission set |
| Web server + PKCE | Apps that sign in individual users | Callback URL, PKCE on; users approve in Salesforce |
| Refresh token | Keeping a web-server session alive | Set a refresh token policy; Salesforce's CLI guide suggests 90 days or less, and a 15-minute session timeout |
| ~~Username-password~~ | Don't use it | The OAuth username-password flow is retired on February 20, 2027 (release update "Retirement of OAuth 2.0 Username-Password Flow for Connected Apps"). Orgs created in Summer '26 or later already block it, and ECAs never supported it. A blocked request gets invalid_grant / authentication failure |
Also retiring: SOAP login() in Summer '27 (jsforce's loginBySoap warns about it). jsforce's own deprecation note suggests the OAuth username-password flow as the replacement; given the retirement above, use client credentials or JWT instead.
Scopes
| Need | Scopes |
|---|---|
| REST, SOQL, metadata as an integration | api, plus refresh_token offline_access when a refresh token is wanted |
| CLI login | api, web, refresh_token offline_access |
| Agent API | api, refresh_token offline_access, chatbot_api, sfap_api |
For the Agent API, Salesforce's setup also selects:
- Enable Client Credentials Flow;
- Issue JWT-based access tokens for named users.
It deselects the secret and PKCE requirements for the web server and refresh token flows. The Run As user needs at least API Only access. The token response carries api_instance_url (https://api.salesforce.com), the Agent API host (family 5 covers the Agent API).
Users and permissions for these apps: reference/access/users-permissions-and-agent-users.md. Errors: reference/auth/oauth-and-session-errors.md.