---
cuppy_hub: salesforce
cuppy_path: reference/auth/external-client-apps-and-oauth-flows.md
cuppy_section: docs
cuppy_doc: 9YVT-2ZYJ
cuppy_doc_uuid: f29dda20-5e7a-4551-9456-55d5262867f5
cuppy_permalink: https://cuppy.io/salesforce/d/9YVT-2ZYJ
cuppy_version: 1
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/salesforce/docs/reference/auth/external-client-apps-and-oauth-flows
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: 31f64b3e0089643c7dee7dc9c4182d3306e066478fd68ebfbccce935cd986808
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# 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`.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 376 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/salesforce/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->