Target: Spring '26. Sources: New connected apps can no longer be created in Spring '26, External Client Apps, OAuth flows, Named Credentials.
1. App identity: External Client App, not Connected App
- From Spring '26, creating a Connected App is disabled by default in orgs, through the UI and the Metadata API. Salesforce Support can still grant an exception today; that door is closing.
- Existing Connected Apps keep working, and managed-package installs are unaffected. Every one of them is on a migration path to an External Client App (ECA) — inventory them now and migrate the ones you own.
- An ECA splits what used to be one blob into separate metadata: the app itself, its global OAuth settings (secrets, callback URLs, flow enablement) and its policies (session, IP relaxation, permitted users). That is why ECAs package and deploy cleanly and Connected Apps never did.
- Set up in Setup → External Client App Manager. Deploy as metadata like anything else; keep the consumer secret out of the repo (
$Secret-style references or the pipeline's secret store).
2. Choosing the OAuth flow
| Situation | Flow | Notes |
|---|---|---|
| Server-to-server, no human, client can hold a secret | Client Credentials | Enable it on the ECA and set the Run As integration user. POST /services/oauth2/token with grant_type=client_credentials, client id and secret. The simplest correct choice for a backend job |
| Server-to-server, no secret at rest, high assurance | JWT Bearer | Signed assertion with a certificate you rotate; grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<jwt>. The user must be pre-authorised for the app |
| A real user acts in an app | Authorization Code + PKCE | Mandatory shape for mobile and SPA clients; refresh token policy set deliberately |
| Device with no browser | Device flow | Being retired on Connected Apps — new work goes to an ECA |
| Username-password | never | Blocked in most orgs and always the wrong answer |
Rules for all of them: one integration user per consuming system (attributable usage, revocable in isolation), API-only where the licence allows, permissions from a permission set rather than a profile, IP relaxation chosen deliberately, and a written rotation date for every secret and certificate.
3. Named Credentials and External Credentials (Salesforce calling out)
The pair does the token work so no Apex ever holds a secret:
- External Credential — the authentication protocol (OAuth 2.0, JWT, JWT bearer, AWS Signature V4, Basic, or custom headers) plus its principals:
- Named Principal — one identity for the whole org (the usual integration case).
- Per User Principal — each user authenticates individually (a user acting on their own behalf in a partner system).
- Named Credential — the URL, which External Credential to use, which headers to generate, and whether Apex/Flow may generate headers.
- Access is granted by permission set: a user without the External Credential Principal Access on their permission set gets a callout failure, not a login prompt. This is the most common "it works for me" bug.
- In code and flow the endpoint is
callout:ERP_Api/orders/123— no host, no key, no refresh logic. - Per-user OAuth credentials for a Per User Principal are authorised from the user's settings; build a short runbook for it rather than explaining it per ticket.
4. Inbound users and permissions
Integration_ERP (User, API Only profile or minimum-access profile)
└ Permission Set: ERP_Integration
Object: Order__c (Create, Read, Edit) — no Delete
Field: Order__c.ERP_Id__c (Read, Edit)
Apex class: OrderApi
System: API Enabled
Bypass: Ignore_Validation_Rules__c on the integration user ← migration windows only
- Never reuse a human's account for an integration, and never give the integration user "Modify All Data" because a test failed — find the missing object or field permission instead.
- Freeze rather than delete a retired integration user; its records keep their owner.
- For inbound Apex REST, class access goes on the permission set too — a missing class permission looks like a 403 with no detail.
5. Migration checklist — Connected App → ECA
- Inventory: Setup → Connected Apps OAuth Usage, plus
ConnectedApplicationin the Metadata API and any packaged apps (packaged ones are the vendor's job) - For each app you own: which flow, which integration user, which consumers hold the client id/secret
- Create the ECA with the same flows, scopes and callback URLs; keep the old app live during cutover
- Re-issue client id/secret to consumers, or re-sign the JWT against the new app
- Switch one consumer, watch Login History and API usage for that user, then the rest
- Retire the Connected App only after a full quiet period, and record the date in the integration design document
- Recheck session and IP policies on the ECA — they are separate metadata and do not carry over silently