Module 01 - Fundamentals

Goal: Build the mental model. Just vocabulary and pictures, so every later module makes sense. API version: v66.0 (Spring '26). Outcome: you can explain integration to a non-technical person in one minute and define every core term without hesitating.

This module is the foundation for the whole vault. Read the files in order (01 → 10), or jump to a concept via the map below. Everything later (Authentication, APIs, Events, Bulk) assumes the words and ideas defined here.

How to use this module

1. Start with 01-what-and-why-of-integration.md for the big picture and the three questions every integration answers.
2. Lock in the vocabulary with 02-core-vocabulary.md, then work through the "vs" files (they are short and high-yield).
3. Finish with 09 (the capstone model) and 10 (why Salesforce is special).
4. Use the glossary table below as your quick-reference cheat sheet.

Map of this module

The one model that ties it all together

Every integration is just one choice from each of three layers. Pin this picture and the rest is detail.

Example: a Salesforce REST API call = HTTPS + JSON + OAuth 2.0 Bearer token. Full detail in 09-three-layers-transport-format-auth.md.

Vocabulary quick-reference (glossary)

What changed worth knowing (2025-2026)

• SOAP API login() is retiring in Summer '27 (not available in API v65.0+, disabled by default in new orgs). Migrate API authentication to OAuth via External Client Apps. Detail in 03-rest-vs-soap.md and Module 03.
• REST + JSON is the default for new builds; SOAP + XML is legacy-but-supported.
• For real-time event push, Pub/Sub API is the modern choice over older Streaming API.

Where this leads

After this module you have the vocabulary. Module 02 (Integration Patterns) teaches when to use each style, and Module 03 (Authentication) is already built out in full.

Sources (Verified June 2026)

• Integration Patterns and Practices (v66.0) — Salesforce Architect
• Platform Multitenant Architecture — Salesforce Architect
• SOAP API login() Retirement — Salesforce Help
• Salesforce Developers — API documentation

Each topic file has its own Sources section with the specific official docs.

01 - What Integration Is (and Why Salesforce Needs It)

One-liner: Integration is just two systems talking to each other so data and actions flow between them instead of being re-typed by hand. Why it matters: Salesforce is almost never the only system a business runs. Its value multiplies when it shares data with the website, the ERP, the payment gateway, the data warehouse, and the phone system. Goal of this file: Be able to explain integration to a non-technical person in one minute.

This is Module 01. No deep code yet, just the mental model and vocabulary. Each later file builds on the picture drawn here.

1. The idea in plain English

Picture two people who speak different languages trying to do business. They need three things: a way to reach each other (a phone line), a shared language (so the words mean the same thing), and proof of who they are (so neither gets scammed). Software systems are exactly the same. Salesforce and an external system each store their own data in their own shapes. Integration is the agreed-upon phone call between them.

Without integration, a human becomes the integration: someone exports a CSV from the website, opens Salesforce, and re-types 200 leads. That is slow, error-prone, and always out of date. An integration replaces that human with an automatic, reliable connection.

2. Why integrate Salesforce? (the business drivers)

Every integration exists to serve one of a few goals. In an interview, name the driver, not just the tech.

3. The shape of every integration (3 questions)

Before choosing any API or auth method, answer these three questions. The rest of this vault is just detailed answers to them.

1. Who is talking? Salesforce calling out, an external system calling in, or both. (See 06-inbound-vs-outbound.md.)
2. How do they prove identity? The authentication layer. (Whole of Module 03.)
3. What style of conversation? Real-time or batch, request/reply or fire-and-forget, REST or SOAP. (Files 03, 05, 07.)

4. How it shows up in Salesforce

Concrete examples you can name in an interview:

• Website → Salesforce: a "Contact Us" form posts to the Salesforce REST API and creates a Lead. (Inbound, request/reply.)
• Salesforce → Payment gateway: Apex makes an HTTP callout through a Named Credential to charge a card. (Outbound, request/reply.)
• Salesforce → ERP: when an Opportunity closes, Salesforce publishes a Platform Event that the ERP subscribes to. (Outbound, fire-and-forget.)
• Nightly sync: an ETL tool loads 2 million records via Bulk API 2.0. (Batch, async.)
• Live data: an Account page shows SAP invoices through Salesforce Connect without copying them. (Data virtualization.)

Platform note: Salesforce is API-first — almost everything you can do in the UI, you can do through an API. That is why integration is a first-class skill, not an afterthought.

5. Common confusions and interview traps

6. Interview Q&A

Q: Explain integration to a non-technical stakeholder. A: It is an automatic, reliable connection that lets two systems share data and trigger actions, so people don't have to copy information between them by hand.

Q: Why would a company integrate Salesforce instead of just using it standalone? A: To keep one source of truth across systems, automate manual work, give users real-time data, reach capabilities Salesforce lacks (payments, scoring), and offload heavy processing. The driver should be a business need, not the technology.

Q: What are the first questions you ask when scoping an integration? A: Who initiates (inbound vs outbound), how identity is proven (auth), and the conversation style (real-time vs batch, request/reply vs event). Those three decisions drive the API and pattern choice.

Q: Is integration always real-time? A: No. Much of it is scheduled batch or asynchronous events. Real-time adds cost and tighter coupling, so you choose it only when the use case truly needs a fresh response.

Talking point to explain it to anyone: "It's the difference between emailing a coworker a spreadsheet to retype, versus the two apps just texting each other automatically."

7. Key terms

API, endpoint, payload, request/response, inbound/outbound, synchronous/asynchronous, webhook, middleware — all defined in 02-core-vocabulary.md and the README glossary.

Sources (Verified June 2026)

• Integration Patterns and Practices (v66.0, Spring '26) — Salesforce Architect
• Platform Multitenant Architecture — Salesforce Architect
• Salesforce Developers — API overview

Next: 02-core-vocabulary.md — the words you must know before anything else makes sense.

02 - Core Vocabulary (The Words You Must Know)

One-liner: Eight or nine words — API, endpoint, request, response, payload, methods, headers, status codes — unlock almost every integration conversation. Why it matters: Every later topic (REST, SOAP, auth, events) reuses these terms. Get them wrong in an interview and the rest sounds shaky. Goal of this file: Read one real Salesforce REST call and name every part of it.

New here? Start with 01-what-and-why-of-integration.md for the big picture.

1. The idea in plain English

Think of ordering at a restaurant. You don't walk into the kitchen and cook. You talk to a waiter through a fixed routine: you give an order (a request), the kitchen does the work, and the waiter brings back a plate (a response). The menu tells you what you're allowed to ask for. You never touch the stove.

An API is that waiter. It is the agreed set of things one system will do for another, and the exact way to ask. You send a request to a specific address, the system does the work, and it sends a response back. Everything below is just naming the parts of that exchange.

2. The vocabulary, one term at a time

Endpoint vs Base URL: the base URL is https://MyDomainName.my.salesforce.com. The endpoint is the full path you hit, e.g. https://MyDomainName.my.salesforce.com/services/data/v66.0/sobjects/Account. Salesforce returns your base URL as instance_url when you authenticate.

3. HTTP methods (what each verb does in REST)

REST maps the four basic data operations (often called CRUD — Create, Read, Update, Delete) onto HTTP verbs. Memorize this table.

Interview note: Salesforce updates use PATCH, not PUT. PUT in the Salesforce REST API is reserved for upsert by external ID (create-or-update). Mixing these up is a common slip. Idempotent means repeating the same call leaves the system in the same state — GET, PATCH, PUT, and DELETE are idempotent; POST is not.

4. Headers (the two that matter most)

Headers are Name: Value lines that travel with the request. For integrations, two are non-negotiable:

Bearer token: "Bearer" means whoever holds this token gets access, like cash. That is why tokens live in a header over HTTPS and are guarded like passwords. The token itself comes from Module 03 (authentication).

5. HTTP status codes (the three families)

The first digit tells you the family. Learn the family first, then the common members.

The mental rule: 2xx = "great." 4xx = "your fault." 5xx = "their fault." In Salesforce, an expired session shows up as 401 INVALID_SESSION_ID, and hitting your daily API limit shows up as 403 REQUEST_LIMIT_EXCEEDED.

6. A real Salesforce request and response

Putting every term together. Here we create an Account via the REST API (API version v66.0, Spring '26).

The request (POST = create):

POST /services/data/v66.0/sobjects/Account HTTP/1.1
Host: MyDomainName.my.salesforce.com
Authorization: Bearer 00D5g000004...!AQEAQ...
Content-Type: application/json

{
  "Name": "Acme Corp",
  "Industry": "Technology",
  "NumberOfEmployees": 250
}

• Method = POST (create). Endpoint = /services/data/v66.0/sobjects/Account.
• Headers = Authorization (the token) and Content-Type (the payload is JSON).
• Payload = the JSON object with the field values.

The response — status 201 Created:

{
  "id": "001gK000004xZpQQAU",
  "success": true,
  "errors": []
}

• Status code 201 = a new record was created.
• Payload = the new record's id, a success flag, and an empty errors array.

7. How it shows up in Salesforce

• The base URL is your My Domain instance (e.g. acme.my.salesforce.com), returned as instance_url after login.
• Almost every data endpoint sits under /services/data/vXX.X/. The vXX.X is the API version — v66.0 is Spring '26.
• Authorization: Bearer <token> is on nearly every call; the token is a temporary Session ID.
• A 201 means a record was created; the response gives you its 15- or 18-character record Id.
• A 401 mid-session almost always means the token expired — refresh it. A 403 often means a permission problem or an API limit.

8. Common confusions and interview traps

9. Interview Q&A

Q: What is an API, in one sentence? A: A contract that defines what one system can ask another to do, and exactly how to ask — like a waiter taking a structured order to the kitchen and bringing back the plate.

Q: Difference between an endpoint and a base URL? A: The base (instance) URL is the server's root address, like https://acme.my.salesforce.com. An endpoint is the full path you actually call, like .../services/data/v66.0/sobjects/Account. One base URL exposes many endpoints.

Q: Which HTTP method updates a record in Salesforce REST, and what's the trap? A: PATCH for a partial field update. The trap is assuming PUT — in the Salesforce REST API, PUT is used for upsert by external ID, not a normal update.

Q: A call returns 401. What does it mean and what do you do? A: The request isn't authenticated — usually an expired or missing access token (INVALID_SESSION_ID). You get a fresh token (refresh flow) and retry. A 403, by contrast, means you're authenticated but lack permission or hit an API limit.

Q: What's in an HTTP request versus a response? A: A request has a method, an endpoint URL, headers (auth, content type), and an optional payload/body. A response has a status code, headers, and a body. The status code's first digit tells you the outcome family: 2xx success, 4xx client error, 5xx server error.

Q: What does Authorization: Bearer mean? A: It carries an access token where possession equals access. The server trusts whoever presents a valid token, so it must travel over HTTPS and be protected like a password.

Talking point to explain it to anyone: "It's a restaurant order. You ask the waiter (the API) for something specific (the endpoint), hand over your details and your order (headers and payload), and get back a plate with a note saying how it went (the response and its status code)."

10. Key terms

API, endpoint, base/instance URL, request/response, payload, HTTP methods, headers, status codes — cross-referenced in the README glossary. Next we use them to compare the two API styles.

Sources (Verified June 2026)

• REST API Developer Guide — Create a Record (v66.0)
• REST API Developer Guide — Working with Records (HTTP methods)
• Salesforce Developers — API overview
• HTTP response status codes — MDN
• HTTP request methods — MDN

Next: 03-rest-vs-soap.md — the two API styles, and why new Salesforce builds favor REST.

03 - REST vs SOAP (The Two API Styles)

One-liner: REST and SOAP are two ways to build a web API — REST is lightweight and resource-based, SOAP is a strict, contract-driven XML protocol. The core difference: REST uses plain HTTP verbs on resources and usually speaks JSON; SOAP wraps every message in a rigid XML envelope defined by a WSDL contract. Why it matters: Salesforce ships both. New builds default to REST, but SOAP is still everywhere in older integrations — and one big SOAP auth change is landing in 2026-2027.

Need the words first? See 02-core-vocabulary.md.

1. The idea in plain English

Two ways to send a parcel.

REST is like standard post. You write the address on the box (the URL), drop it in (a verb like GET or POST), and the system knows what to do. Light, flexible, everyone supports it.

SOAP is like registered mail with a notarized form. Every parcel must go inside a specific envelope, with a strictly formatted form attached (the XML envelope), and a master rulebook (the WSDL) defines exactly what every field must look like. More ceremony, but the contract is ironclad and machine-readable — tools can auto-generate client code from the WSDL.

Neither is "better" everywhere. SOAP is a protocol with built-in rules; REST is an architectural style that leans on HTTP itself.

2. The core difference, side by side

One-line interview answer: "REST is lightweight, resource-and-verb based, and usually JSON. SOAP is a heavier XML protocol with a strict WSDL contract and built-in standards. New work goes REST; SOAP lives on in mature enterprise systems."

3. The same call in both styles

REST — create an Account (compact, JSON, verb in the method):

POST /services/data/v66.0/sobjects/Account
Content-Type: application/json

{ "Name": "Acme Corp" }

SOAP — create an Account (envelope, namespaces, everything is XML):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:urn="urn:partner.soap.sforce.com">
  <soapenv:Header>
    <urn:SessionHeader><urn:sessionId>00D...!AQ...</urn:sessionId></urn:SessionHeader>
  </soapenv:Header>
  <soapenv:Body>
    <urn:create>
      <urn:sObjects xsi:type="Account">
        <Name>Acme Corp</Name>
      </urn:sObjects>
    </urn:create>
  </soapenv:Body>
</soapenv:Envelope>

Same outcome, very different weight. Note SOAP carries the session in a SessionHeader inside the envelope, while REST carries it in the Authorization HTTP header.

4. How it shows up in Salesforce

Salesforce exposes both, and you should be able to name them:

Salesforce publishes two WSDLs for the SOAP API: the Enterprise WSDL (strongly typed to one org's schema) and the Partner WSDL (loosely typed, works across orgs). New builds favor REST for its simplicity and lighter footprint.

Platform note: this is which style to call Salesforce with. It is separate from authentication (Module 03) and from data format (next file). A SOAP API call still needs a session; a REST call still needs a bearer token.

5. CURRENT and important — SOAP API login() is being retired

This is a live, exam-worthy change. Say it precisely:

• The SOAP API login() call (the old way of trading username + password for a session) is being retired in Summer '27 for SOAP API versions 31.0 through 64.0. After that release, those login() calls stop working and every dependent integration fails to authenticate.
• login() is not available in API version 65.0 and later at all.
• From the Summer '26 release, in newly created orgs the SOAP login() call is disabled by default; an admin must enable it, and once enabled, users need the new "Use Any API Auth" user permission to authenticate this way.
• Salesforce's guidance: migrate to OAuth — Web Server flow, JWT Bearer flow, or Client Credentials flow — configured through External Client Apps, well before the cutoff.

Interview gold: "SOAP isn't dying — the SOAP login() authentication call is. Salesforce is pushing everyone onto OAuth and External Client Apps. If I owned a legacy SOAP integration that calls login(), I'd plan a migration to JWT Bearer or Client Credentials before Summer '27." See Module 03 for those flows.

6. When to use which

Common confusions and traps

7. Interview Q&A

Q: What's the core difference between REST and SOAP? A: REST is a lightweight architectural style that uses HTTP verbs on resources and usually returns JSON. SOAP is a strict protocol where every message is an XML envelope defined by a mandatory WSDL contract. REST is lighter and dominant for new work; SOAP offers a rigid, strongly typed contract favored in legacy enterprise systems.

Q: Which does Salesforce recommend for new integrations, and why? A: REST. It's simpler, less verbose, JSON-friendly, easy to test and debug, and fits web/mobile and microservice patterns. SOAP remains supported for existing systems and WSDL-based tooling.

Q: How does error handling differ? A: REST uses HTTP status codes (201, 400, 401, 500) plus a JSON error body. SOAP returns a SOAP Fault element, usually inside an HTTP 200 response, so you must parse the envelope rather than rely on the status code alone.

Q: What's the SOAP login() retirement about? A: The SOAP API login() call — username/password for a session — is being retired in Summer '27 for API versions 31.0-64.0 and is already absent in v65.0+. From Summer '26 it's disabled by default in new orgs and gated by the "Use Any API Auth" permission. Salesforce wants migration to OAuth (Web Server, JWT Bearer, or Client Credentials) via External Client Apps. The SOAP API itself stays; only that auth call goes away.

Q: When would you still pick SOAP today? A: When integrating with middleware or partners that consume a WSDL, when a strict typed contract is required, or when the only Salesforce API for the job is SOAP-based (parts of Metadata API). Otherwise REST.

Talking point to explain it to anyone: "REST is standard post — write the address, drop it in. SOAP is registered mail with a notarized form: more paperwork, but the contract is airtight."

8. Key terms

REST, SOAP, WSDL, envelope, SOAP Fault, JSON, XML, OAuth — see 02-core-vocabulary.md and the README glossary. Auth flows live in Module 03.

Sources (Verified June 2026)

• Platform SOAP API login() Retirement — Salesforce Help
• SOAP API login() Call in Versions 31.0-64.0 Is Being Retired — Release Notes
• SOAP API End-of-Life Policy — SOAP API Developer Guide
• Which API Do I Use? — Salesforce Help
• REST API Developer Guide — Introduction

Next: 04-json-vs-xml.md — the two data formats these APIs carry.

04 - JSON vs XML (The Two Data Formats)

One-liner: JSON and XML are two ways to write structured data as text so two systems can exchange it. The core difference: JSON is compact key/value data, native to web/JavaScript; XML is verbose tag-based markup with namespaces, attributes, and schemas. Why it matters: REST and most modern Salesforce APIs speak JSON; SOAP API and Metadata API speak XML. Knowing which goes where avoids a lot of confusion.

Coming from the API styles? See 03-rest-vs-soap.md. New words live in 02-core-vocabulary.md.

1. The idea in plain English

Both are just text that carries structured data — a way to write down "this record has these fields with these values" so another program can read it back exactly.

JSON (JavaScript Object Notation) is like a packing list: short labels and values, Name: Acme, with curly braces grouping things. Minimal punctuation, easy for a human to skim and for a browser to parse.

XML (eXtensible Markup Language) is like a legal form: every field is wrapped in an opening and closing tag, <Name>Acme</Name>, and you can attach extra notes (attributes), declare which rulebook applies (namespaces), and validate against a schema. More words on the page, but very explicit.

Neither is "the data" — they are two spellings of the same data. A record is a record; JSON and XML are just how you write it down on the wire.

2. The same record in both formats

A single Contact — first name, last name, email, and whether they're active — written both ways.

JSON:

{
  "FirstName": "Ada",
  "LastName": "Lovelace",
  "Email": "ada@example.com",
  "IsActive": true
}

XML:

<Contact>
  <FirstName>Ada</FirstName>
  <LastName>Lovelace</LastName>
  <Email>ada@example.com</Email>
  <IsActive>true</IsActive>
</Contact>

Same four fields. JSON is ~80 characters lighter here, and the structure is implied by braces and quotes rather than repeated tags. XML repeats every field name twice (open and close) but can carry extra metadata JSON cannot express as cleanly.

3. The core difference, side by side

One-line interview answer: "JSON is compact key/value data that maps straight to objects and dominates REST and the web. XML is verbose tag-based markup with namespaces, attributes, and strong schema validation — the language of SOAP, Metadata API, and config files."

4. How it shows up in Salesforce

The mapping is clean and worth memorizing:

So in practice: when you call the REST API you send and receive JSON; when you deploy metadata or call the SOAP API, you're in XML. Every Salesforce metadata file on disk (CustomObject, Flow, ApexClass meta) is XML.

Platform note: a package.xml manifest for a Metadata API deploy is pure XML with namespaces. A record returned from GET /services/data/v66.0/sobjects/Contact/003... is JSON. Same platform, two formats, chosen by the API.

5. When to use which

Common confusions and traps

6. Interview Q&A

Q: What's the core difference between JSON and XML? A: JSON is a compact key/value format with native data types that maps directly to objects — dominant in REST and the web. XML is verbose, tag-based markup that supports namespaces, attributes, and strict schema validation — the language of SOAP and config. They're two spellings of the same structured data.

Q: In Salesforce, which APIs use which format? A: REST API, Bulk API 2.0, and Connect API use JSON. SOAP API and Metadata API use XML. Tooling API is typically JSON. As a rule: REST means JSON, SOAP and metadata mean XML.

Q: Can the Salesforce REST API return XML? A: Yes. JSON is the default, but you can request XML via the Accept header. The point is that format and API style are independent choices — REST just defaults to the lighter format.

Q: Why is JSON usually preferred for new web integrations? A: It's compact, parses natively in JavaScript and most languages, maps cleanly to objects, and has less overhead than XML's open/close tags. That makes it faster and simpler for app and mobile work.

Q: When does XML still win? A: When you need namespaces to avoid name clashes, attributes to attach metadata, comments, or rigorous XSD validation — and whenever you're in SOAP, Metadata API, or Salesforce config files, which are XML by design.

Talking point to explain it to anyone: "JSON is a packing list — short labels and values. XML is a legal form — every field wrapped in a labeled box, with room for stamps and rules. Same information, different amount of paperwork."

7. Key terms

JSON, XML, key/value, tag/element, attribute, namespace, schema (XSD/JSON Schema), envelope — see 02-core-vocabulary.md and the README glossary. API styles are in 03-rest-vs-soap.md.

Sources (Verified June 2026)

• REST API Developer Guide — Introduction (JSON default)
• Metadata API Developer Guide — Introduction (XML)
• SOAP API Developer Guide — Introduction (XML/WSDL)
• JSON — MDN Web Docs
• XML introduction — MDN Web Docs

Next: 05-synchronous-vs-asynchronous.md — request/reply now vs fire-and-forget later.

05 - Synchronous vs Asynchronous

One-liner: Synchronous = the caller waits for the answer before doing anything else. Asynchronous = the caller fires the request and moves on, getting the result later via a poll, callback, or event. Why it matters: This single choice decides your user experience, your throughput, and how you handle failure. Pick wrong and you either freeze a screen for 30 seconds or lose track of work that finished in the background. Core difference in one line: Sync blocks and gives you an immediate answer. Async doesn't block and hands you the answer later.

New here? Skim 01-what-and-why-of-integration.md first for the big picture.

1. The idea in plain English

Imagine ordering food two ways.

Synchronous is a phone call to a busy hotline. You dial, you stay on the line, you cannot do anything else, and you hang up only once you have your answer. Fast when the other side answers quickly. Painful when they put you on hold.

Asynchronous is texting the restaurant. You send "one large pizza," put your phone in your pocket, and go water the plants. A while later a text pings back: "Ready for pickup." You were never stuck waiting.

In software, synchronous means the calling code pauses on that line until a response arrives. Asynchronous means the call returns instantly with a "got it, I'll handle it," and the real result shows up later through a callback, a status you poll, or an event you subscribe to.

2. The core difference + side-by-side comparison

The whole distinction is does the caller block and wait? Everything else flows from that.

3. A concrete example

Charging a credit card (synchronous). A user clicks "Pay." Your code calls the payment gateway and waits for "approved" or "declined" before it can show the next screen. The user must know the outcome right now, so blocking is the correct design. The cost: if the gateway is slow, the user stares at a spinner.

Loading 2 million records into a warehouse (asynchronous). An ETL tool submits a job, gets back a job id instantly, and walks away. Salesforce processes the records in the background. The tool checks back later, or gets notified, when the job completes. Nobody could sit and wait 40 minutes on a single open connection, so async is the only sane choice.

4. How it shows up in Salesforce

Salesforce draws this line very clearly. Know which side each tool sits on.

Synchronous in Salesforce:

• REST API and SOAP API request/reply. You call, you wait, you get rows back in the same response. Best for a handful of records.
• Apex HTTP callouts (outbound). A callout blocks the running transaction. Each callout can run up to a 120-second timeout (default 10s, set with setTimeout), and a single transaction allows up to 100 callouts. Synchronous callout response size is capped at 6 MB.

Asynchronous in Salesforce:

• Bulk API 2.0. You submit a job, get a job id, and poll for completion. Built for thousands to millions of records, processed in the background. (REST/SOAP, by contrast, are tuned for real-time small batches.)
• Platform Events and the Pub/Sub API. Publish an event and move on. Subscribers receive it later over a streaming channel. Pure fire-and-forget.
• @future methods. Mark an Apex method @future and it runs later in its own background context. The classic way to make a callout from a trigger without blocking.
• Queueable Apex. Like @future but with chaining and a job id you can monitor. The modern default for background work.
• Batch Apex. Processes large data sets in chunks asynchronously, ideal for nightly jobs.

Async callouts get more room. Asynchronous Apex allows a larger callout response (12 MB vs 6 MB for synchronous). Another reason heavy work belongs in the background.

Why a trigger uses @future for callouts. You cannot make a synchronous callout in the same transaction that has uncommitted DML, and you do not want a user's save to block on a slow external system. So you defer the callout to an async method.

5. When to use which + common confusions

Rule of thumb: small + fast + user-needs-it-now → synchronous. Big + slow + fire-and-forget → asynchronous.

6. Interview Q&A

Q: Explain synchronous vs asynchronous. A: Synchronous means the caller blocks and waits for the response before continuing. Asynchronous means the caller sends the request, gets an immediate acknowledgement, keeps working, and receives the real result later through a poll, callback, or event.

Q: Give a Salesforce example of each. A: Synchronous: a REST API query or an Apex HTTP callout to charge a card, where the transaction waits for the response. Asynchronous: Bulk API 2.0 loading millions of records, or publishing a Platform Event that subscribers pick up later.

Q: Why can't a trigger just make a synchronous callout directly? A: A callout is not allowed in a transaction with pending uncommitted DML, and you do not want the user's save blocked on a slow external system. So you defer it with @future or Queueable Apex, which run asynchronously.

Q: A callout to a slow partner API keeps timing out. What do you change? A: A synchronous callout maxes out at 120 seconds. Move the work to an asynchronous pattern. Queueable Apex, Batch Apex, or a job-and-poll design, so the user is not blocked and you control retries.

Q: When would you choose synchronous even though async scales better? A: When the caller cannot continue without the answer. Payments, real-time validations, and "show me this record now" lookups all need a synchronous response.

Q: What is the trade-off you accept by going asynchronous? A: Looser coupling and higher throughput in exchange for more complex result handling. You no longer get a single success/fail in one place. You must track job status, handle out-of-band failures, and design retries and notifications.

Talking point to explain it to anyone: "Synchronous is a phone call. You wait on the line for the answer. Asynchronous is a text message. You send it and get on with your day until a reply pings back."

7. Key terms

Synchronous, asynchronous, blocking, callback, polling, callout, timeout, fire-and-forget, job id, throughput, latency — all defined in 02-core-vocabulary.md and the README glossary.

Sources (Verified June 2026)

• Bulk API 2.0 — Salesforce Developers (v66.0, Spring '26)
• Asynchronous Processing — Salesforce Architects Decision Guide
• Callout Limits and Limitations — Apex Developer Guide
• Pub/Sub API — Salesforce Developers
• Future Methods — Apex Developer Guide

Next: 06-inbound-vs-outbound.md — which direction is the call going, into Salesforce or out of it?

06 - Inbound vs Outbound

One-liner: Inbound = an external system calls into Salesforce. Outbound = Salesforce calls out to an external system. The direction is always measured relative to Salesforce. Why it matters: Direction decides who authenticates whom, which APIs and tools you reach for, and which side is the "client" and which is the "server." Get the direction right and the auth and tooling fall into place. Core difference in one line: Inbound, someone calls Salesforce. Outbound, Salesforce calls someone.

New here? Read 01-what-and-why-of-integration.md and 05-synchronous-vs-asynchronous.md first.

1. The idea in plain English

Stand inside Salesforce and watch the front door.

Inbound is someone knocking on your door. A delivery driver (an external app) shows up, proves who they are, and hands you a package or asks for one. Salesforce is the host. It must check the visitor's ID before letting them in.

Outbound is you leaving the house to visit someone else. Salesforce walks out, knocks on the partner's door, and proves its own identity to them. Now Salesforce is the visitor.

The only thing that flips is who initiates the call. The same business integration often has both directions: the website calls in to create a lead (inbound), and later Salesforce calls out to a billing system when a deal closes (outbound).

2. The core difference + side-by-side comparison

Memory hook: Follow the arrow. If the arrow points at Salesforce, it is inbound. If it points away, it is outbound.

3. A concrete example

Inbound: a web form creates a Lead. A "Contact Us" page on the company website POSTs to the Salesforce REST API. The website app first authenticates using a Connected App and an OAuth token, then calls POST /services/data/v66.0/sobjects/Lead. Salesforce is the server here. It checks the token, then creates the record. The external app had to prove it was allowed in.

Outbound: Salesforce charges a card. When an Opportunity closes, Apex makes an HTTP callout through a Named Credential to the payment gateway. Salesforce is now the client. The Named Credential holds the endpoint and the credentials Salesforce uses to authenticate to the gateway. Salesforce is the visitor proving who it is.

Same company, both directions, completely different auth setup on each side.

4. How it shows up in Salesforce

Inbound (Salesforce is the destination):

• REST API and SOAP API. The standard front doors for external apps to create, read, update, and delete records.
• Apex REST (@RestResource) and Apex SOAP web services (webservice keyword). Custom endpoints you build in Apex when the standard APIs are not enough, exposing your own URLs and logic.
• Every inbound caller must authenticate first. The external app is registered as a Connected App or External Client App, and uses OAuth to get an access token. (See Module 03.)

Outbound (Salesforce is the source):

• Apex HTTP callouts. Apex code that sends an HTTP request to an external endpoint.
• Named Credentials (with External Credentials). The recommended way to store the endpoint URL and authentication so callout code never hardcodes secrets. Salesforce handles the token for you.
• External Services. Point Salesforce at an external API's schema and it generates invocable actions you can call from Flow, no code.
• Outbound Messages (legacy). A workflow/Flow action that sends a SOAP message to an endpoint when a record changes. A single message can carry up to 100 notifications. Mature but dated, covered more in 07-push-pull-and-webhooks.md.

The auth tie, stated plainly: - Inbound → Salesforce is the resource server. The external app holds the credentials and proves itself to Salesforce. Your job is to register the app and grant the right scopes. - Outbound → Salesforce is the client. Salesforce holds the credentials (in a Named Credential) and proves itself to the partner. Your job is to configure the Named/External Credential.

5. When to use which + common confusions

Rule of thumb: ask "who picked up the phone and dialed?" If it was the external system, inbound. If it was Salesforce, outbound.

6. Interview Q&A

Q: Define inbound and outbound integration in Salesforce. A: Inbound means an external system initiates a call into Salesforce. Salesforce is the server. Outbound means Salesforce initiates a call out to an external system. Salesforce is the client. Direction is measured relative to Salesforce.

Q: For an inbound integration, who authenticates to whom, and how? A: The external app authenticates to Salesforce. It is registered as a Connected App or External Client App and uses OAuth to obtain an access token, which it sends as a bearer token on each API call. Salesforce acts as the resource server.

Q: For an outbound callout, where do the credentials live? A: In a Named Credential paired with an External Credential on the Salesforce side. They store the endpoint and how Salesforce authenticates to the partner, so Apex callout code never hardcodes URLs or secrets.

Q: Name the inbound tools and the outbound tools. A: Inbound: REST API, SOAP API, Apex REST, Apex SOAP web services. Outbound: Apex HTTP callouts, Named Credentials, External Services, and the legacy Outbound Messages.

Q: A partner needs to push order updates into Salesforce. Inbound or outbound, and what do you set up? A: Inbound. The partner calls the Salesforce REST API (or a custom Apex REST endpoint). You register their app as a Connected App or External Client App, grant the api scope, and they authenticate via OAuth.

Q: Salesforce needs to notify an ERP when an Opportunity closes. Inbound or outbound? A: Outbound. Salesforce initiates. Options include an Apex HTTP callout through a Named Credential, an External Services action, or a legacy Outbound Message. For event-style delivery you might publish a Platform Event the ERP subscribes to.

Talking point to explain it to anyone: "Inbound is someone knocking on Salesforce's door. Outbound is Salesforce leaving the house to knock on someone else's. Whoever knocks has to prove who they are."

7. Key terms

Inbound, outbound, client, server, resource server, Connected App, External Client App, Named Credential, External Credential, Apex REST, callout — all defined in 02-core-vocabulary.md and the README glossary. Auth roles are detailed in Module 03 fundamentals.

Sources (Verified June 2026)

• Integration Patterns and Practices (v66.0, Spring '26) — Salesforce Architect
• REST API Developer Guide — Salesforce Developers
• Named Credentials as Callout Endpoints — Apex Developer Guide
• Outbound Messaging — SOAP API Developer Guide
• Authorize Apps with OAuth — Salesforce Help

Next: 07-push-pull-and-webhooks.md — does the consumer ask for data, or does the producer push it the moment it changes?

07 - Push, Pull, and Webhooks

One-liner: Pull = the consumer asks for data when it wants it. Push = the producer sends data the moment something changes. A webhook is a push: an HTTP callback the producer fires to a URL the consumer registered in advance. Why it matters: This is the difference between data that is always a little stale and burns resources, versus data that arrives the instant it changes. Most "why is my integration so slow / so chatty" problems trace back to choosing pull where push belonged. Core difference in one line: Pull, you go fetch it. Push, it comes to you.

New here? Read 01-what-and-why-of-integration.md, then 05 and 06.

1. The idea in plain English

Think about how you find out the news.

Pull is refreshing a news website. Nothing reaches you until you go and ask. To stay current you have to keep hitting refresh, over and over, even when nothing has changed. Most of those refreshes are wasted, and between refreshes your view is out of date.

Push is a breaking-news alert on your phone. You signed up once, then you do nothing. The moment something happens, the alert lands. No wasted checks, no lag.

A webhook is the breaking-news alert formalized for software. The consumer says, "here is my URL, call it when X happens." The producer keeps that URL and fires an HTTP request to it the instant X happens. The consumer waits passively and reacts.

Polling (pull) is wasteful and laggy: most polls return "nothing new," and real changes wait until the next poll. Push is efficient and fresh: a message is sent only when there is something to say, and it arrives immediately.

2. The core difference + side-by-side comparison

The trade-off in one line: pull is simple but laggy and chatty. Push is fresh and lean but needs more plumbing (a live endpoint, retries, and security).

3. A concrete example

Pull: nightly inventory sync. A reporting tool calls the Salesforce REST API once a night to fetch the day's orders. Freshness does not matter. Yesterday's data is fine in the morning. A scheduled pull is simple and perfectly adequate.

Push: notify shipping the instant an order is paid. The moment an Opportunity flips to "Paid," the warehouse needs to know now, not at the next nightly poll. Salesforce publishes a Platform Event (or fires a callout to the warehouse's webhook URL). The warehouse reacts within seconds. Polling here would mean either an unacceptable delay or hammering the API every few seconds just in case.

4. How it shows up in Salesforce

Salesforce supports both, and importantly does not use the word "webhook" in its product names. It achieves the same outcome with events (consumers subscribe) and callouts (Salesforce fires an HTTP request to a registered URL).

Pull in Salesforce (the consumer asks):

• REST / SOAP query. An external system runs a SOQL query or GET request whenever it wants the current data.
• Scheduled jobs. Scheduled Apex or an external ETL tool polls on a timer (every night, every hour) to fetch what changed.

Push in Salesforce (the producer sends):

• Platform Events. Salesforce publishes a custom event. Subscribers receive it over a streaming channel. The event-driven backbone.
• Change Data Capture (CDC). Salesforce automatically publishes an event whenever records are created, updated, deleted, or undeleted, carrying the changed fields. No code to publish.
• Pub/Sub API. The modern, unified, gRPC-based API to publish and subscribe to Platform Events, CDC, and real-time event-monitoring events. It uses binary Avro payloads over HTTP/2 and is the recommended subscriber interface.
• Outbound Messages (legacy). A workflow/Flow action that pushes a SOAP message to a registered endpoint URL when a record changes, up to 100 notifications per message. This is the closest classic Salesforce feature to a webhook.
• Webhook-style callouts from Flow or Apex. To call an external webhook, Salesforce fires an HTTP callout (from a record-triggered Flow or Apex) to the URL the partner gave you. Salesforce is the producer pushing out.

Webhook, the Salesforce way: a webhook is just "producer fires HTTP to a URL the consumer registered." Salesforce does the inbound side by being an endpoint (an Apex REST resource an external producer calls) and the outbound side by firing a callout or publishing an event. The mechanism has a different name, but the pattern is identical.

Why push beats polling for freshness. Polling every 5 minutes means data is up to 5 minutes stale and you make 288 calls a day even on quiet days. A push delivers in seconds and sends nothing when nothing changed. Push trades that efficiency for needing a reliable listener.

5. When to use which + common confusions

Rule of thumb: need it the instant it changes → push (events / callouts). Periodic or on-demand is fine → pull (query / scheduled job).

6. Interview Q&A

Q: Explain push vs pull. A: Pull means the consumer asks the producer for data when it wants it, often by polling on a timer. Push means the producer sends data to the consumer the moment something changes. Pull is simple but laggy and wasteful. Push is fresh and efficient but needs more infrastructure.

Q: What is a webhook? A: A webhook is a push delivered over HTTP. The consumer registers a URL with the producer in advance, and the producer fires an HTTP request to that URL whenever the relevant event happens. It is a callback rather than something the consumer polls for.

Q: Does Salesforce have webhooks? A: Not under that name. Salesforce achieves the same push pattern with Platform Events, Change Data Capture, and the Pub/Sub API for subscribers, and with HTTP callouts or legacy Outbound Messages when Salesforce fires to an external URL.

Q: When would you poll instead of using events? A: When freshness is not critical and simplicity matters, such as a nightly or hourly batch sync, or when the external system cannot host a reliable listener endpoint. A scheduled pull is easy to build and easy to recover.

Q: What is the downside of polling, and how does push fix it? A: Polling is laggy (data is stale between polls) and wasteful (most polls return nothing new, yet still consume API calls). Push fixes both by sending a message only when something changes, and delivering it within seconds.

Q: Compare Outbound Messages with Platform Events. A: Both push data out, but Outbound Messages are legacy. They send a SOAP message to one endpoint, tied to workflow or Flow. Platform Events are the modern event bus. Many subscribers, richer payloads, and consumed over the Pub/Sub API. New designs favor Platform Events and CDC.

Talking point to explain it to anyone: "Pull is refreshing a website to see if anything changed. Push is a notification that pings you the instant it does. A webhook is just that notification, but for two apps."

7. Key terms

Push, pull, polling, webhook, callback, event, publish/subscribe, Platform Event, Change Data Capture, Pub/Sub API, Outbound Message, streaming — all defined in 02-core-vocabulary.md and the README glossary.

Sources (Verified June 2026)

• Pub/Sub API — Salesforce Developers
• Platform Events Developer Guide — Salesforce Developers
• Change Data Capture Developer Guide — Salesforce Developers
• Outbound Messaging — SOAP API Developer Guide
• Subscribe to Platform Events with Pub/Sub API — Salesforce Developers

Next: 08-middleware-and-esb.md — the broker in the middle that connects many systems without point-to-point spaghetti.

08 - Middleware and the ESB (the glue layer)

One-liner: Middleware is software that sits between two systems and connects, translates, routes, and orchestrates the traffic between them. Why it matters: As soon as you have more than a couple of systems, wiring them directly to each other becomes a tangle. Middleware is the hub that keeps it clean, and MuleSoft (owned by Salesforce) is the name you must know.

New here? Read 01-what-and-why-of-integration.md first for the big picture.

1. The idea in plain English

Imagine an office where everyone needs to talk to everyone else. If each person runs their own phone wire to every other person, you get a wall of spaghetti. Add one new hire and you have to run a wire from them to everybody. Now picture a switchboard in the middle instead. Everyone plugs into the switchboard once, and it routes calls, translates languages, and keeps a log. Adding a new hire means one wire to the switchboard.

Middleware is that switchboard for software. It is the layer in the middle that:

• Connects systems that speak different protocols.
• Translates data from one format or shape into another.
• Routes a message to the right destination based on rules.
• Orchestrates multi-step flows ("call A, then B, then write to C").
• Throttles traffic so a slow system is not overwhelmed.

Without it, every system talks directly to every other system. That works for one or two links. It collapses at scale.

2. Point-to-point vs a middleware hub

This is the single most important picture in this file. The same six systems, two ways of wiring them.

In point-to-point, N systems can need up to N x (N-1) / 2 connections. Six systems means up to 15 brittle links, each with its own auth, format, and error handling. In hub-and-spoke, each system connects once to the hub. The hub absorbs the change. Add a seventh system and you add one spoke, not six new wires.

3. ESB vs iPaaS (old hub vs new hub)

There are two generations of the "hub" idea. Interviewers like to hear that you know the difference and the direction of travel.

Plain version: an ESB is a heavy switchboard you buy, install, and run in your own server room. An iPaaS is the same idea rented as a cloud service, so you skip the hardware and get a library of ready-made plugs.

Note: the line blurs in practice. Modern MuleSoft can run in the cloud, on-prem, or hybrid. The clean exam answer is "ESB = older, heavy, often on-prem hub; iPaaS = modern, cloud, subscription hub."

4. MuleSoft - the name to know

MuleSoft makes the Anypoint Platform, the leading iPaaS. Salesforce acquired MuleSoft in 2018, so when an interviewer asks "how does Salesforce do enterprise integration at scale?", MuleSoft is the headline answer.

What to remember:

• API-led connectivity is MuleSoft's signature methodology. MuleSoft pioneered the idea. Instead of one-off integrations, you build reusable, purposeful APIs in three tiers and compose them:
• System APIs unlock a backend (Salesforce, SAP, a database).
• Process APIs combine and orchestrate data across systems.
• Experience APIs shape that data for a specific channel (mobile, web, partner).
• Anypoint Platform bundles iPaaS and full lifecycle API management (design, deploy, secure, monitor) in one place.
• It sells reuse as the win: build the "Customer" System API once, reuse it everywhere, instead of re-integrating Salesforce for every project.

Platform note: from inside Salesforce you can directly invoke MuleSoft APIs and flows, which is why the two are pitched as one connected stack. You do not need MuleSoft for every integration. A single Apex callout to one API needs no middleware at all.

5. When you need middleware (and when you don't)

Rule of thumb: middleware buys you decoupling and reuse at the cost of another system to run and pay for. Justify it with the number of connections and the need to transform or orchestrate, not because it sounds enterprise-grade.

6. Interview Q&A

Q: What is middleware? A: Software that sits between two or more systems and connects, translates, routes, and orchestrates the data flowing between them. It is the switchboard in the middle instead of a wire between every pair of systems.

Q: Point-to-point vs hub-and-spoke. Why does it matter? A: Point-to-point connects every system directly, so connections grow roughly with the square of the number of systems and become brittle spaghetti. A middleware hub has each system connect once to the center, so adding a system adds one spoke. It trades direct simplicity for decoupling and reuse.

Q: ESB vs iPaaS? A: An ESB is the older, heavy, often on-premises enterprise bus you host yourself. An iPaaS is the modern cloud version, delivered as a subscription with pre-built connectors and API management. MuleSoft's Anypoint Platform is the leading iPaaS.

Q: What is MuleSoft and how does it relate to Salesforce? A: MuleSoft makes the Anypoint Platform, the leading iPaaS, and is known for API-led connectivity. Salesforce acquired it in 2018, so it is Salesforce's enterprise integration and API management offering. You can invoke MuleSoft APIs directly from Salesforce.

Q: When would you NOT use middleware? A: When you have only one or two simple connections, both sides speak the same protocol and format, and there is no orchestration or throttling needed. A single Apex callout to one REST API does not need a hub. Adding middleware there is overhead with no payoff.

Talking point to explain it to anyone: "It is the difference between everyone in the office running a phone wire to everyone else, versus everyone plugging into one switchboard in the middle that routes and translates the calls."

7. Key terms

Middleware, ESB, iPaaS, MuleSoft, Anypoint Platform, API-led connectivity, hub-and-spoke, point-to-point, orchestration, throttling, protocol bridging - defined in 02-core-vocabulary.md and the README glossary.

Sources (Verified June 2026)

• What is MuleSoft? - Salesforce
• MuleSoft Anypoint Platform - Salesforce
• Integration Patterns and Practices (v66.0, Spring '26) - Salesforce Architect

Next: 09-three-layers-transport-format-auth.md - the single mental model that every integration is built from.

09 - The Three Layers: Transport, Format, Auth

One-liner: Every integration is built from three layers - how the bytes travel (transport), how the data is structured (format), and how identity is proven (auth). Why it matters: This is the capstone mental model of Module 01. Once you see it, choosing an integration becomes "pick one from each layer," and any Salesforce API stops being a mystery.

New here? Read 01-what-and-why-of-integration.md first.

1. The idea in plain English

Think about mailing a letter. Three things must be true for it to work:

1. A way to travel - the postal road, a truck, a plane. (Transport)
2. A language inside the envelope - English, French, a shared alphabet. (Format)
3. Proof of who sent it - a return address, a signature, a wax seal. (Auth)

Change any one and the other two still apply. You can send English by truck or by plane. You can sign a letter written in any language. The three concerns are independent, and you choose one option for each.

Software integration is identical. Every single integration, no matter the vendor, answers the same three questions:

• TRANSPORT - how do the bytes physically move between the two systems?
• FORMAT - how is the data inside structured so both sides understand it?
• AUTH - how does the caller prove it is allowed to do this?

Choosing an integration = picking one option from each layer. For example:

A Salesforce REST API call = HTTPS (transport) + JSON (format) + OAuth 2.0 Bearer token (auth).

That one sentence is the whole module in a nutshell.

2. The three layers (the signature visual)

Read it top to bottom: pick a transport, pick a format, pick an auth method, and the combination is your integration. Different Salesforce APIs simply make different picks.

3. The three layers, one at a time

Transport - how the bytes travel

The pipe the data flows through.

Format - how the data is structured

The shape of the payload once it arrives. (Deep dive in 04-json-vs-xml.md.)

Auth - how identity is proven

The proof the caller is allowed in. (Whole of Module 03.)

4. A concrete example

A web form on your company site needs to create a Lead in Salesforce. Walk the three layers:

1. Transport - the form posts over HTTPS so the data is encrypted in transit.
2. Format - the body is JSON: { "LastName": "Khan", "Company": "Acme" }.
3. Auth - the server attaches an OAuth 2.0 Bearer token in the Authorization header.

Put together, the call is:

POST https://MyDomainName.my.salesforce.com/services/data/v66.0/sobjects/Lead
Authorization: Bearer 00D...!AQ...
Content-Type: application/json

{ "LastName": "Khan", "Company": "Acme" }

POST ... HTTPS is the transport. Content-Type: application/json and the body are the format. Authorization: Bearer ... is the auth. Three layers, one request.

5. How it shows up in Salesforce (the mapping table)

This table is worth memorizing. Name any Salesforce API and you can recite its three layers.

Pattern to notice: the auth layer is almost always OAuth 2.0 across Salesforce. What really differs between APIs is the transport and format. That is why Module 03 (auth) is largely shared across every API, while transport and format are what you pick per use case.

6. Common confusions and interview traps

7. Interview Q&A

Q: Give me a single mental model for any integration. A: Three independent layers. Transport is how the bytes travel (HTTP/HTTPS, gRPC, CometD). Format is how the data is structured (JSON, XML, Protobuf). Auth is how identity is proven (OAuth 2.0, API key, mTLS, Basic). Every integration picks one from each.

Q: Break a Salesforce REST call into the three layers. A: Transport is HTTPS, format is JSON, auth is an OAuth 2.0 Bearer token in the Authorization header. Change the transport or format and you have a different API, but the auth layer stays OAuth in nearly all cases.

Q: How does Pub/Sub API differ from REST API in this model? A: Same auth layer (OAuth 2.0), but a different transport and format. Pub/Sub uses gRPC over HTTP/2 with Protobuf, which is binary and efficient for streaming, whereas REST uses HTTPS with JSON.

Q: HTTPS already encrypts the call. Why do I still need OAuth? A: Different layers solving different problems. HTTPS (transport) protects the data in transit so it cannot be read or tampered with. OAuth (auth) proves the caller is who they claim and is allowed to do this. Encryption is not identity.

Q: Where does this model send you next when designing an integration? A: Transport choice points you at which API to use, format is detailed in the data formats file, and auth is the whole of Module 03. The model turns one big decision into three smaller, well-scoped ones.

Talking point to explain it to anyone: "It is like mailing a letter. You need a way to travel, a language inside, and proof of who sent it. Software picks one of each, and that combination is the integration."

8. Key terms

Transport, format, auth, HTTP/HTTPS, gRPC, CometD, long-polling, JSON, XML, Protobuf, OAuth 2.0, Bearer token, API key, mTLS, Basic auth - defined in 02-core-vocabulary.md and the README glossary. Auth detail lives in Module 03. Format detail lives in 04-json-vs-xml.md.

Sources (Verified June 2026)

• Which API Do I Use? - Salesforce Help
• REST API Developer Guide (v66.0, Spring '26) - Salesforce Developers
• Pub/Sub API Documentation - Salesforce Developers
• SOAP API Developer Guide - Salesforce Developers

Next: 10-salesforce-as-a-platform.md - why "platform" changes how you design every integration.

10 - Salesforce as a Platform (why it changes integration)

One-liner: Salesforce is not just an app you log into. It is a multitenant, metadata-driven platform with APIs on everything and strict limits, and those four traits shape how you must design every integration. Why it matters: If you design an integration as if Salesforce were a private server you own, you will hit runtime errors in production. Understanding the platform is what separates a junior from a senior integration engineer.

This is the final file of Module 01. It ties the whole module together.

1. The idea in plain English

A regular app is like a single house you own. You control the wiring, you can run the dishwasher and the dryer at the same time, nobody else is affected.

Salesforce is like an apartment building. Many tenants share the same plumbing, the same electrical supply, the same elevators. To keep it fair and safe, the building has rules: don't run every appliance at once, don't hog the elevator, quiet hours apply. The building manager (Salesforce) enforces those rules automatically, and if you break them, the power to your unit trips.

That apartment building is multitenancy, and the rules are governor limits. Once you internalize that you are a tenant sharing infrastructure, every design decision in this module makes sense.

2. The four traits that matter

1. Multitenant

Many customers share the same infrastructure. A single instance of Salesforce runs a shared multitenant database and a multitenant kernel (the application runtime). The kernel reads each tenant's metadata and serves up an app that behaves like it is yours alone. This is why your org feels private even though you share servers with thousands of others.

2. API-first

Nearly everything you can do in the Salesforce UI is also available through an API. Creating records, running queries, deploying metadata, subscribing to events - all callable programmatically. This is why integration is a first-class skill on this platform and not an afterthought.

3. Governor limits

Because resources are shared, Salesforce strictly enforces limits so no single tenant can starve the others. Exceed a limit and you get a runtime error, not a slow response. Limits are the guardrails of multitenancy. (Detailed below.)

4. Metadata-driven and event-capable

Your objects, fields, validation rules, and logic are stored as metadata that the kernel materializes at runtime. The platform is also event-capable: it can publish and subscribe to events (Platform Events, Change Data Capture), enabling real-time, decoupled integration.

3. The metadata-driven kernel serving many orgs

One kernel, one shared database, but each org's metadata makes it behave like its own application. The governor limits wrap every org as guardrails, keeping one tenant from hurting the rest.

4. Governor limits (the ones that bite integrations)

These exist purely because the platform is shared. Know that they exist and roughly what they cap. Exact numbers vary by edition and change across releases, so describe them rather than memorizing figures unless you have checked the current docs.

Important: treat the precise allocation numbers as "look it up for the current release and edition." The interview-safe move is to describe the limit and the design response, not to quote a figure you might get wrong. (Verified ranges are in Sources below.)

5. Why this changes how you design integrations

This is the payoff of the whole module. Because Salesforce is a shared platform with limits, three habits are mandatory:

One sentence to carry forward: on a shared platform you design for fairness and scale, which in practice means bulkify, count your API calls, and prefer async for anything large.

6. Common confusions and interview traps

7. Interview Q&A

Q: What does it mean that Salesforce is a platform, not just an app? A: It is multitenant (many customers share one infrastructure), metadata-driven (a kernel builds each org's app from metadata at runtime), API-first (nearly everything in the UI is also callable through an API), and event-capable. Those traits, plus enforced limits, shape every integration you build on it.

Q: What is multitenancy and why should an integration engineer care? A: Many customers share the same database and application kernel, isolated by metadata. You care because shared resources mean enforced governor limits. You must bulkify, watch your API allocation, and design for fairness, since you are not the only tenant.

Q: What are governor limits and why do they exist? A: Runtime caps on resources like API calls per day, concurrent long-running requests, callouts per transaction, and per-transaction SOQL/DML/CPU. They exist because the platform is shared, so no single tenant can monopolize resources. Exceeding one throws a runtime error.

Q: How do platform limits change your integration design? A: Three ways. Bulkify so logic handles record sets, not singletons. Respect the daily API allocation by batching calls and using composite endpoints. Go asynchronous for large volume using Bulk API 2.0, Platform Events, or async Apex, rather than many synchronous calls.

Q: A nightly job needs to load two million records. How do you approach it given the platform? A: Not record-by-record through the REST API, which would burn the daily allocation and hit concurrency limits. Use Bulk API 2.0, which is asynchronous and built for large volumes, processing data in server-side batches that respect the shared-platform constraints.

Talking point to explain it to anyone: "Salesforce is an apartment building, not a private house. Everyone shares the plumbing, so there are house rules. Design your integration like a good neighbor: don't run every appliance at once, and do the big laundry loads off-peak."

8. Key terms

Platform, multitenant, metadata-driven, kernel, API-first, governor limits, API request allocation, concurrent requests, bulkify, asynchronous, Platform Events, Bulk API 2.0 - defined in 02-core-vocabulary.md and the README glossary.

Sources (Verified June 2026)

• Platform Multitenant Architecture - Salesforce Architect
• API Request Limits and Allocations - Salesforce Developer Limits Quick Reference
• Execution Governors and Limits - Apex Developer Guide
• Callout Limits and Limitations - Apex Developer Guide
• API Limits and Monitoring Your API Usage - Salesforce Developers Blog

Next: back to the README.md module index. From here, the natural continuation is Module 02 - Integration Patterns, where these fundamentals turn into concrete design choices (request/reply, fire-and-forget, batch, data virtualization, and more).

Module 02 - Integration Patterns

Goal: Memorize the 6 official Salesforce integration patterns and know exactly when to use which. API version: v66.0 (Spring '26). Outcome: given any integration requirement, point at one pattern and justify it in a sentence.

A pattern is a named, reusable answer to a recurring integration problem. Salesforce's official Integration Patterns and Practices guide defines six. Master these and you can scope any integration before touching code. New to the vocabulary (sync/async, inbound/outbound, push/pull)? Read Module 01 first.

How to use this module

1. Read the patterns in order (01 → 06). Each is short and built the same way.
2. Use the decision tree and comparison table below as your interview cram sheet.
3. For the auth behind any callout or inbound call, see Module 03 - Authentication.

Map of this module

Which pattern? (decision tree)

The master comparison table (memorize this)

Scenario → pattern (quick mapping)

Interview rapid-fire

Q: Request & Reply vs Fire & Forget? → Reply waits for and uses the response (sync). Forget sends and moves on (async). Choose by whether the result drives the next step.

Q: A partner wants to push orders into Salesforce. Which pattern and tech? → Remote Call-In via the REST API (or Apex REST for custom logic), authenticated with a Connected App / External Client App + OAuth.

Q: 5 million records nightly. Which pattern? → Batch Data Sync with Bulk API 2.0, upserting by External ID, scheduled off-peak. Never loop synchronous callouts.

Q: Show live external data without storing it? → Data Virtualization with Salesforce Connect (External Objects over OData). Each view triggers a callout, so mind performance.

Q: Make an LWC refresh instantly when a record changes? → UI Update on Change using Change Data Capture / Pub/Sub API, with the LWC subscribing via lightning/empApi.

Sources (Verified June 2026)

• Integration Patterns and Practices (v66.0, Spring '26) — Salesforce Developers
• Pattern Selection Guide — Salesforce Developers
• Pattern Summary — Salesforce Developers

Each pattern file has its own Sources section with the specific official doc.

01 - Request and Reply

One-liner: Salesforce calls an external system, waits for the answer, and uses it right away. Direction: Salesforce → External (outbound). Timing: Synchronous. Volume: Low, one record/transaction at a time. Use when: A user or process needs an immediate response before continuing.

This is Module 02, the integration patterns. New to the vocabulary (sync/async, inbound/outbound)? See Module 01. For the auth behind callouts, see Module 03.

1. The idea in plain English

Request and Reply is a phone call. You dial, you ask your question, and you stay on the line until the other person answers. You cannot continue your day until you hear back. If they do not pick up, or take too long, your whole call fails.

In Salesforce terms: Apex (or Flow) makes an HTTP callout to an external service, the user or transaction blocks until the response arrives, and the result is shown or saved immediately. Think of a rep clicking "Check Credit Score" and seeing the score appear two seconds later. That round-trip, in-the-moment answer is the whole pattern.

2. When to use it (and when not)

Real-world examples: real-time credit check during loan creation, address validation on a form, fetching live inventory/price before quoting, a payment authorization call.

3. How it works (sequence diagram)

Walkthrough

1. A user action or process kicks off the transaction.
2. Apex or Flow makes an outbound HTTP callout (through a Named Credential, so no hardcoded secrets).
3. Salesforce waits synchronously for the reply. The transaction is paused.
4. The external system returns data.
5. Salesforce parses it and acts (saves a field, makes a decision).
6. Control returns to the user with the result.

4. How it shows up in Salesforce (the tech)

Minimal Apex shape (note the Named Credential, never a hardcoded URL or token):

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:Credit_Service/score?ssn=' + ssn);
req.setMethod('GET');
req.setTimeout(120000); // max 120s
HttpResponse res = new Http().send(req);
if (res.getStatusCode() == 200) {
    Map<String,Object> body = (Map<String,Object>) JSON.deserializeUntyped(res.getBody());
    // use body, save to record
}

Auth: outbound callouts authenticate with a Named Credential + External Credential. See Module 03 - Named Credentials.

5. Design considerations and gotchas

6. Interview Q&A

Q: What is the Request and Reply pattern? A: Salesforce calls an external system synchronously and waits for the response before continuing. It is for real-time, low-volume calls where you need the answer immediately, like a credit check at the point of sale.

Q: How do you implement it in Salesforce? A: An Apex HTTP callout (or Flow HTTP Callout / External Services for low-code), authenticated through a Named Credential. The transaction blocks until the response returns.

Q: What are the main limits to watch? A: 120-second max callout timeout, 100 callouts per transaction, and you cannot make a callout after uncommitted DML. If the service is slow or volume is high, move to async or batch instead.

Q: How is this different from Fire and Forget? A: Request and Reply waits for and uses the response. Fire and Forget sends a message and moves on without waiting. Use Reply when the result drives the next step, Forget when it does not.

Q: The external API takes 5 minutes. Now what? A: Do not hold a synchronous transaction. Switch to an asynchronous approach: queue the work (Queueable/@future) or redesign as Fire and Forget with a callback, so the user is not blocked and you avoid the timeout.

Talking point to explain it to anyone: "It's a phone call. You ask, you wait on the line, you get your answer, then you act on it."

7. Key terms

HTTP callout, Named Credential, synchronous, timeout, idempotency, External Services - defined in Module 01 vocabulary and the README.

Sources (Verified June 2026)

• Request and Reply - Integration Patterns and Practices (v66.0)
• Pattern Selection Guide - Salesforce Developers
• Apex Callouts - Apex Developer Guide

Next: 02-fire-and-forget.md - when Salesforce sends a message and does not wait for a reply.

02 - Fire and Forget

One-liner: Salesforce announces that something happened and moves on. It does not wait for a reply. Direction: Salesforce → External (outbound). Timing: Asynchronous. Volume: Many small events, near real time. Use when: You need to broadcast a business event ("OrderShipped") and you do not need an answer back.

This is Module 02, the integration patterns. New to the vocabulary (sync/async, inbound/outbound, pub/sub)? See Module 01. For the auth behind callouts and event subscribers, see Module 03.

1. The idea in plain English

Fire and Forget is posting a letter. You write it, drop it in the mailbox, and walk away. You trust the postal service to deliver it. You do not stand at the box waiting for the recipient to read it and reply. Your day continues immediately.

In Salesforce terms: a process publishes an event (or sends a one-way message) describing something that just happened, then the transaction continues without blocking. One or more external subscribers pick the message up later and do their own work. The publisher and subscriber are loosely coupled — neither has to be online at the same time, and the publisher does not care who is listening or what they do with it.

Contrast this with Request and Reply, which is a phone call you stay on the line for. Here, you hang up before anyone answers.

2. When to use it (and when not)

Real-world examples: publish OrderShipped so a logistics app and a notification service both react; emit LeadConverted for a marketing platform; send a legacy ERP a one-way AccountUpdated notice via Outbound Message; fan a PaymentReceived event out to several downstream systems.

3. How it works (sequence diagram)

Walkthrough

1. A user action or backend process completes some work.
2. Salesforce publishes a platform event to the event bus (or sends a one-way Outbound Message).
3. Salesforce does not block — control returns to the user/process right away.
4. The transaction finishes normally.
5. The event bus delivers the message to each external subscriber asynchronously, on their schedule.
6. Each subscriber processes independently and owns its own error handling.
7. If a subscriber was offline, it can replay missed events by Replay ID within the retention window.

4. How it shows up in Salesforce (the tech)

The official guide gives Fire and Forget two main implementation options: the modern event-driven approach (Platform Events) and the legacy declarative approach (Outbound Messages).

Publish a Platform Event from Apex (no hardcoded endpoint — subscribers connect to the bus):

// OrderShipped__e is a Platform Event with custom fields
OrderShipped__e evt = new OrderShipped__e(
    OrderId__c   = order.Id,
    TrackingNo__c = trackingNumber,
    ShippedAt__c = System.now()
);
Database.SaveResult sr = EventBus.publish(evt);
if (!sr.isSuccess()) {
    for (Database.Error err : sr.getErrors()) {
        System.debug('Publish failed: ' + err.getMessage());
    }
}

For an async one-way HTTP notify instead of an event, the outbound callout still goes through a Named Credential — never a hardcoded URL or secret:

@future(callout=true)
public static void notifyExternal(Id orderId) {
    HttpRequest req = new HttpRequest();
    req.setEndpoint('callout:Logistics_API/v1/shipped');
    req.setMethod('POST');
    req.setHeader('Content-Type', 'application/json');
    req.setBody(JSON.serialize(new Map<String,Object>{ 'orderId' => orderId }));
    new Http().send(req); // fire it; we do not act on the response
}

Auth: Outbound callouts use a Named Credential + External Credential. External subscribers to events authenticate to the Pub/Sub/Streaming API via OAuth. See Module 03 - Named Credentials and Module 03 README.

5. Design considerations and gotchas

6. Interview Q&A

Q: What is the Fire and Forget pattern? A: Salesforce publishes a message or event about something that happened and continues without waiting for a reply. It is asynchronous, loosely coupled, and used to broadcast business events like "OrderShipped" where you do not need an answer back.

Q: What are the two main ways to implement it in Salesforce? A: The modern, recommended way is Platform Events — publish from Apex/Flow/API and let external subscribers consume via the Pub/Sub API or CometD. The legacy way is Outbound Messages — a declarative SOAP message sent from Flow to a fixed endpoint, with automatic retry.

Q: How is delivery guaranteed for each? A: They differ. Outbound Messages retry automatically with backoff for about 24 hours until acknowledged. Platform Events publish to the bus once with no Salesforce-side retry; durability comes from the 72-hour replay window — the subscriber resumes from its last Replay ID. Both are effectively at-least-once, so subscribers must be idempotent.

Q: How does this differ from Request and Reply? A: Request and Reply is synchronous — Salesforce waits for and uses the response. Fire and Forget sends and moves on. Use Reply when the result drives the next step; use Forget when announcing a fact to one or many systems.

Q: A subscriber was down for an hour. Did it lose the events? A: Not if it acts within the retention window. Platform Events keep high-volume messages for 72 hours; the subscriber replays from the Replay ID of the last event it processed. Outbound Messages retry until acknowledged or until they expire (~24h).

Talking point to explain it to anyone: "It's posting a letter. You drop it in the box and walk away — you trust it gets there, you don't wait for a reply."

7. Key terms

Platform Events, event bus, Pub/Sub API, CometD, Replay ID, Outbound Message, Change Data Capture, idempotency, eventual consistency, at-least-once delivery - defined in Module 01 vocabulary and the README. Deeper dive in Module 06 - Event-Driven.

Sources (Verified June 2026)

• Remote Process Invocation - Fire and Forget (Integration Patterns, v66.0)
• Platform Events Developer Guide
• Platform Event Allocations
• Considerations for Outbound Messages - Salesforce Help
• Pub/Sub API - Event Message Durability

Next: 03-batch-data-synchronization.md - moving large data sets on a schedule, both directions, off-peak.

03 - Batch Data Synchronization

One-liner: Move large volumes of data between Salesforce and another system on a schedule, usually overnight. Direction: Both ways (Salesforce → External and External → Salesforce). Timing: Scheduled / batch. Volume: HIGH, off-peak. Use when: You need a nightly sync of big datasets between Salesforce and an ERP or data warehouse.

This is Module 02, the integration patterns. New to the vocabulary (sync/async, ETL, upsert, External ID)? See Module 01. For the auth a middleware tool uses to reach Salesforce, see Module 03.

1. The idea in plain English

Batch Data Synchronization is the overnight delivery truck. You do not send a courier for every single parcel (that would be one-at-a-time Request and Reply). Instead, you let parcels pile up all day, then a big truck runs once at night when the roads are empty and hauls everything in one trip. It is slow per parcel but extremely efficient for volume.

In Salesforce terms: a scheduled job extracts or loads thousands to millions of records in batches, typically during off-peak hours so it does not compete with daytime users or burn the daily API budget. The goal is to keep two systems in agreement — Salesforce and an ERP, a data warehouse, or a billing platform — without hammering them in real time.

Contrast this with Fire and Forget (one small event at a time) and Request and Reply (one synchronous round-trip). Batch is the heavyweight for bulk.

2. When to use it (and when not)

Real-world examples: nightly ERP → Salesforce product/price catalog refresh; hourly Salesforce → data warehouse export of closed opportunities for BI; daily account/contact reconciliation with a master data system; bulk migration during a go-live.

3. How it works (flowchart)

Walkthrough

1. A scheduler (cron, middleware, or a Salesforce scheduled job) kicks off the run during off-peak hours.
2. Delta sync: extract only records that changed since the last run (using a timestamp or high-water mark), not the whole table.
3. A middleware/ETL layer transforms and maps fields between the two data models.
4. The data is loaded asynchronously in batches via Bulk API 2.0.
5. The load uses upsert keyed on an External ID so each row either updates a match or inserts a new record.
6. Bulk API returns per-batch success and error results.
7. Failed rows are logged, alerted on, and retried; the run records a new high-water mark for the next delta.

4. How it shows up in Salesforce (the tech)

Upsert by External ID is the heart of safe batch sync. The External ID column lets the same job both match-and-update and insert, with no duplicates. A Bulk API 2.0 ingest job specifies it like this:

POST /services/data/v66.0/jobs/ingest
{
  "object": "Account",
  "operation": "upsert",
  "externalIdFieldName": "ERP_Id__c",
  "contentType": "CSV"
}

Then upload the CSV (keep each file within Salesforce's recommended size), close the job, and poll for results. Conceptually:

# 1. Create the job (above)  ->  returns a jobId and contentUrl
# 2. PUT the CSV data to the contentUrl
# 3. PATCH the job state to "UploadComplete"
# 4. GET .../jobs/ingest/{jobId}            -> watch state = JobComplete
# 5. GET .../successfulResults  and  .../failedResults

A scheduled Apex job to trigger an export or downstream processing (the callout itself uses a Named Credential, never a hardcoded secret):

global class NightlySyncJob implements Schedulable {
    global void execute(SchedulableContext ctx) {
        // enqueue work; outbound calls go through callout:Warehouse_API
        System.enqueueJob(new ExportClosedOppsQueueable());
    }
}
// Schedule: System.schedule('Nightly Sync', '0 0 2 * * ?', new NightlySyncJob());

Auth: A middleware tool authenticates to Salesforce as a system integration user, typically via OAuth 2.0 JWT Bearer or Client Credentials (no interactive login). See Module 03 - JWT Bearer and the Module 03 README.

5. Design considerations and gotchas

6. Interview Q&A

Q: What is the Batch Data Synchronization pattern? A: Moving large volumes of data between Salesforce and another system on a schedule, usually overnight, to keep them in agreement. It is asynchronous, high-volume, and latency-tolerant — the opposite of a real-time call.

Q: Which Salesforce technology do you use, and why? A: Bulk API 2.0, because it is built for asynchronous high-volume load and extract and chunks the work into batches automatically. Usually orchestrated by ETL/middleware (MuleSoft, Informatica) that handles scheduling, transformation, and retries.

Q: How do you avoid creating duplicates? A: Upsert keyed on an External ID — a stable, unique key shared with the source system. Each row updates a match or inserts if none exists. This also makes the job idempotent, so a re-run after a partial failure is safe.

Q: What is delta sync and why does it matter? A: Only extracting and loading records that changed since the last run, tracked with a timestamp or high-water mark, instead of the whole dataset. It dramatically cuts API usage, runtime, and load on both systems.

Q: Why run off-peak, and what limit are you protecting? A: To avoid slowing daytime users and to protect the 24-hour rolling API request allocation (Enterprise Edition starts around 100,000 and scales with licenses). Off-peak windows leave headroom and reduce contention.

Talking point to explain it to anyone: "It's the overnight delivery truck. Parcels pile up all day, then one big truck hauls them all at night when the roads are empty."

7. Key terms

Bulk API 2.0, ETL, middleware, upsert, External ID, delta sync, high-water mark, idempotency, off-peak, API allocation - defined in Module 01 vocabulary and the README. Deeper dive in Module 07 - Bulk and Async.

Sources (Verified June 2026)

• Batch Data Synchronization (Integration Patterns, v66.0)
• Bulk API 2.0 - Developer Guide
• Upsert Records (Bulk API 2.0, External ID)
• API Request Limits and Allocations - Quick Reference

Next: 04-remote-call-in.md - when an external system calls into Salesforce to create, read, or update data.

04 - Remote Call-In

One-liner: An external system calls into Salesforce to create, read, update, or delete data. Salesforce is the listener. Direction: External → Salesforce (inbound). Timing: Synchronous or asynchronous. Volume: One record to bulk. Use when: A website creates a Lead in Salesforce, or an ERP pushes order updates into Salesforce.

This is Module 02, the integration patterns. New to the vocabulary (inbound/outbound, REST/SOAP, idempotency)? See Module 01. The external app must authenticate first — see Module 03.

1. The idea in plain English

Remote Call-In flips the direction. In the earlier patterns Salesforce picked up the phone and dialed out. Here, Salesforce is the shop with a front counter, and an outside customer walks in to do business. The external system is the caller; Salesforce exposes a counter (an API) and serves the request — looking up a record, creating one, updating one.

In Salesforce terms: an external app sends an HTTP/SOAP request to a Salesforce API endpoint to perform CRUD on records. Salesforce authenticates the caller, runs the operation under that caller's permissions and sharing, and returns a response. This is the backbone of "a form on our website creates a Lead" or "our ERP keeps Orders in sync by pushing changes."

Because someone else is calling you, the two big themes are security (who is allowed in, and to do what) and resilience (handling retries without creating duplicates).

2. When to use it (and when not)

Real-world examples: a marketing website form creates a Lead; an ERP updates Orders in Salesforce when they ship; a partner portal reads Account status via REST; a mobile app does CRUD through a custom Apex REST endpoint; a billing system bulk-loads invoices via Bulk API.

3. How it works (sequence diagram)

Walkthrough

1. The external app authenticates to Salesforce with OAuth, using credentials from a Connected App / External Client App.
2. Salesforce returns an access token and the instance URL to call.
3. The app sends the actual request (e.g. create a Lead) with Authorization: Bearer <token>.
4. Salesforce enforces authentication, the user's sharing/permissions, and validation rules.
5. The CRUD operation runs against the database.
6. Salesforce returns the result.
7. The app receives an HTTP status code and body (e.g. 201 Created with the new record Id). Using upsert by External ID keeps retries from creating duplicates.

4. How it shows up in Salesforce (the tech)

Inbound calls use either a standard API (no code) or a custom endpoint (Apex). Pick the simplest that meets the contract.

A custom inbound endpoint with Apex REST. Note the upsert by External ID for idempotency and the explicit status code:

@RestResource(urlMapping='/v1/orders/*')
global with sharing class OrderInboundService {

    @HttpPost
    global static String upsertOrder(String externalId, Decimal amount) {
        RestResponse res = RestContext.response;
        try {
            Order__c o = new Order__c(ERP_Id__c = externalId, Amount__c = amount);
            // Upsert on the External ID field -> safe to retry, no duplicates
            upsert o ERP_Id__c;
            res.statusCode = 200;            // 201 if you detect a fresh insert
            return o.Id;
        } catch (Exception e) {
            res.statusCode = 400;            // return a meaningful error code
            return 'ERROR: ' + e.getMessage();
        }
    }
}

The classic Apex SOAP web service equivalent uses the webservice keyword:

global with sharing class OrderSoapService {
    webservice static Id upsertOrder(String externalId, Decimal amount) {
        Order__c o = new Order__c(ERP_Id__c = externalId, Amount__c = amount);
        upsert o ERP_Id__c;
        return o.Id;
    }
}

Auth (read this): the external caller authenticates with a Connected App / External Client App + OAuth. For server-to-server use JWT Bearer or Client Credentials; for user context use the Web Server flow. Salesforce runs the operation under that user's profile, permission sets, and sharing rules — so grant least privilege. Full detail in Module 03 README.

Heads up - SOAP login() retirement: the legacy SOAP API login() call (API versions 31.0-64.0) is being retired in Summer '27. Inbound auth is moving to OAuth (Web Server, JWT Bearer, or Client Credentials). From Summer '26, new orgs also require a Use Any API Auth permission to use SOAP login(). Plan inbound integrations on OAuth, not login().

5. Design considerations and gotchas

6. Interview Q&A

Q: What is the Remote Call-In pattern? A: An external system calls into Salesforce to create, read, update, or delete data. Salesforce is the listener exposing an API. It is inbound — the opposite of Request and Reply, where Salesforce calls out.

Q: What are the main technologies for inbound calls? A: Standard REST API and SOAP API for CRUD, Apex REST (@RestResource) and Apex SOAP web services (webservice keyword) for custom endpoints, Composite API to bundle calls, and Bulk API for high volume.

Q: How does the external app authenticate? A: Through a Connected App / External Client App using OAuth — JWT Bearer or Client Credentials for server-to-server, Web Server flow for user context. Salesforce then runs the operation under that user's permissions and sharing. Grant least privilege. (The old SOAP login() is retiring in Summer '27.)

Q: How do you stop a retried call from creating duplicates? A: Make the endpoint idempotent — expose upsert keyed on an External ID instead of insert, or dedupe on a business key. A repeated call then updates the same record rather than creating a second one.

Q: REST API vs Apex REST — when do you build a custom endpoint? A: Use the standard REST API when plain sObject CRUD is enough — no code. Build Apex REST when you need a custom request/response shape, multi-object or transactional logic, or pre/post processing the standard API cannot express.

Talking point to explain it to anyone: "It's a shop counter. Outside customers walk in to our store (Salesforce) and do business — we check who they are, serve the request, and hand back a receipt."

7. Key terms

REST API, SOAP API, Apex REST, @RestResource, webservice keyword, Composite API, Bulk API, Connected App, External Client App, OAuth, idempotency, least privilege, status codes - defined in Module 01 vocabulary and the README. Deeper dive in Module 04 - Inbound APIs.

Sources (Verified June 2026)

• Remote Call-In (Integration Patterns, v66.0)
• Exposing Apex Classes as REST Web Services
• Platform SOAP API login() Retirement (Summer '27) - Salesforce Help
• API Request Limits and Allocations - Quick Reference

Next: 05-data-virtualization.md - reading and writing external data live, without copying it into Salesforce.

05 - Data Virtualization

One-liner: Salesforce reads external data live, on demand, and never stores a copy. Direction: Salesforce → External (outbound, read at view time). Timing: Synchronous, per view. Volume: One list/record at a time, but it can front a huge external store. Use when: You need to see external data inside Salesforce without copying it.

This is Module 02, the integration patterns. New to the vocabulary (sync/async, callout)? See Module 01. For the auth behind the callout, see Module 03.

1. The idea in plain English

Data Virtualization is a window, not a warehouse. Instead of trucking boxes of data into your house and stacking them in the garage, you cut a window in the wall and look at the warehouse next door. The goods stay where they are. You just see them when you glance through the glass.

In Salesforce terms: you define an External Object that looks and feels like a normal object (records, list views, detail pages, even some relationships), but the rows live in SAP, an Oracle archive, or another Salesforce org. When a user opens the list view, Salesforce makes a live callout to the source, fetches the rows for that screen, and shows them. Close the tab and nothing is stored. This is the opposite of Batch Data Synchronization, which copies data on a schedule.

2. When to use it (and when not)

Real-world examples: show SAP invoices on the Account page, browse a billions-of-rows order archive that was offloaded from the production DB, surface inventory from an ERP, or read records from another Salesforce org without an ETL job.

3. How it works (sequence diagram)

Walkthrough

1. A user opens an External Object list view, report, or detail page.
2. Salesforce hands the request to Salesforce Connect and the configured adapter.
3. The adapter issues a live callout to the source (an OData query for the OData adapter, a REST call for cross-org/Apex).
4. The source returns only the rows for that screen (paged).
5. Salesforce maps the response onto the External Object's fields.
6. The records render. Nothing is persisted. The next view triggers a fresh callout.

4. How it shows up in Salesforce (the tech)

External data is exposed through Salesforce Connect plus an External Data Source and its External Objects (API names end in __x, vs __c for custom objects). You pick an adapter based on the source.

Shape of a custom adapter (the framework calls query when a user views records):

global class ArchiveProvider extends DataSource.Provider {
    override global List<DataSource.Capability> getCapabilities() {
        return new List<DataSource.Capability>{ DataSource.Capability.ROW_QUERY };
    }
    override global List<DataSource.AuthenticationCapability> getAuthenticationCapabilities() {
        return new List<DataSource.AuthenticationCapability>{
            DataSource.AuthenticationCapability.ANONYMOUS
        };
    }
    override global DataSource.Connection getConnection(DataSource.ConnectionParams p) {
        return new ArchiveConnection(); // extends DataSource.Connection, implements query()
    }
}

Auth: the OData and cross-org adapters authenticate with a Named Credential + External Credential, the same plumbing as any callout. See Module 03 - Named Credentials.

5. Design considerations and gotchas

6. Interview Q&A

Q: What is the Data Virtualization pattern? A: Salesforce displays external data live without storing a copy. You define an External Object backed by Salesforce Connect, and Salesforce queries the source on demand when a user views a record or list. It is a window onto the data, not a warehouse copy.

Q: How do you implement it in Salesforce? A: Salesforce Connect with an External Data Source and External Objects (__x). Choose an adapter: the OData adapter for OData endpoints, the Cross-Org adapter for another Salesforce org, or a custom adapter via the Apex Connector Framework for anything else.

Q: When would you copy the data instead (Batch Sync) rather than virtualize it? A: When you need it offline, in large-scale reports, in heavy automation, or with fast complex SOQL and roll-ups. Virtualize when the data must stay in the source, is huge, or is rarely viewed. Copy when Salesforce needs to own and work it.

Q: What are the main limitations of External Objects? A: No standard triggers, no formula fields, no roll-up summaries, limited reporting, and only indirect or external lookup relationships. Each view is a callout subject to limits, and availability tracks the source system's uptime.

Q: The source is slow and the Account page now takes 8 seconds. What do you do? A: Don't virtualize on a hot page. Move the External Object off the critical path (a related list users open deliberately, or a separate tab), page the results, cache where allowed, or switch to a scheduled Batch Sync copy if the page must be fast.

Talking point to explain it to anyone: "It's a window into the warehouse next door. You see the goods live through the glass, but you never haul them into your own garage."

7. Key terms

Salesforce Connect, External Object (__x), External Data Source, OData, Cross-Org adapter, Apex Connector Framework, callout - defined in Module 01 vocabulary and the README.

Sources (Verified June 2026)

• Data Virtualization - Integration Patterns and Practices (v66.0, Spring '26)
• OData Adapters for Salesforce Connect - Salesforce Help
• Get Started with the Apex Connector Framework - Apex Developer Guide
• Salesforce Platform Features Supported by Salesforce Connect - Salesforce Help
• General Limits for Salesforce Connect - Salesforce Help

Next: 06-ui-update-based-on-data-changes.md - when the UI must refresh the instant data changes.

06 - UI Update Based on Data Changes

One-liner: When data changes, an event is pushed so the Salesforce UI refreshes the instant it happens. Direction: Bidirectional (change inside or outside Salesforce → UI). Timing: Asynchronous push, near real-time. Volume: Stream of small events over an event bus. Use when: A dashboard or LWC must auto-refresh the moment a record changes, with no polling.

This is Module 02, the final integration pattern. New to the vocabulary (async, event bus, push)? See Module 01. For the auth behind external subscribers, see Module 03.

1. The idea in plain English

Old way: you keep refreshing your inbox to see if mail arrived. That is polling. Wasteful, slow, and you still miss things between refreshes.

New way: a notification pops the second the mail lands. You did nothing. The mail came to you.

That is this pattern. Instead of a component asking "anything new?" every few seconds, the data change publishes an event to a shared event bus, and any subscriber that cares gets pushed the news immediately. In Salesforce, a Lightning Web Component sitting in the browser subscribes to that stream and updates the screen the moment an event arrives. The change can originate inside Salesforce (a record edit) or outside it (an external system publishes an event), and the UI reacts either way.

2. When to use it (and when not)

Real-world examples: a support console that flashes when a case is reassigned, a sales dashboard that updates as opportunities close, an order tracker that moves when a warehouse system publishes a shipment event, a bid screen in an auction app.

3. How it works (flowchart)

Walkthrough

1. A record changes in Salesforce, or an external system decides something happened.
2. An event is published. Use Change Data Capture (CDC) for record changes, or a custom Platform Event for business signals.
3. The event lands on the event bus, which stores and sequences it and tags each with a replay ID.
4. Subscribers receive a push. Inside the Salesforce UI, an LWC subscribes via lightning/empApi over CometD. Outside Salesforce, services subscribe via the Pub/Sub API.
5. The LWC handler updates component state and the screen refreshes with no user action.

4. How it shows up in Salesforce (the tech)

Two halves: publish the change as an event, then subscribe to it. The subscriber differs depending on whether it is the Salesforce UI or an external system.

Minimal LWC subscriber (note empApi is desktop-only, API 44.0+, and works on the main window only):

import { subscribe, unsubscribe, onError } from 'lightning/empApi';

const CHANNEL = '/data/CaseChangeEvent'; // CDC channel for Case

connectedCallback() {
    subscribe(CHANNEL, -1, (event) => {
        // event.data.payload holds the change. Refresh the UI.
        this.refreshFromEvent(event);
    }).then((sub) => { this.subscription = sub; });

    onError((err) => console.error('Streaming error', err));
}

disconnectedCallback() {
    unsubscribe(this.subscription, () => {});
}

The -1 is a replay option: -1 = only new events from now, -2 = all events still in the retention window, or a specific replay ID to resume exactly where you left off after a disconnect.

Auth: external subscribers using the Pub/Sub API authenticate with OAuth (e.g. the JWT Bearer or Client Credentials flow). See Module 03. The in-browser empApi rides the logged-in user's session, so no extra auth.

5. Design considerations and gotchas

6. Interview Q&A

Q: What is the UI Update Based on Data Changes pattern? A: When data changes, an event is pushed over an event bus and subscribers react in near real time, so the UI refreshes the instant the change happens instead of polling on a timer. The change can come from inside Salesforce (CDC) or outside it (a Platform Event published by another system).

Q: How does a Lightning Web Component get live updates? A: It imports the lightning/empApi module and calls subscribe on a streaming channel (a Platform Event or a CDC channel) over a shared CometD connection. When an event arrives, the callback fires and the component updates its state. It is desktop-only, API 44.0+, main window only.

Q: Pub/Sub API vs the legacy Streaming API. Why does the modern one win? A: Pub/Sub API is gRPC over HTTP/2 with Avro binary payloads and one unified interface to publish and subscribe across Platform Events, CDC, and monitoring events, with flow control and a 72-hour replay window. The legacy Streaming API (PushTopic, generic events over CometD) is no longer enhanced. Use Pub/Sub API for external clients, empApi inside the UI.

Q: What is a replay ID and why does it matter? A: Every event on the bus gets a replay ID marking its position in the stream. If a subscriber disconnects, it reconnects and asks to replay from the last ID it saw, so it catches the events it missed instead of losing them, as long as they are still inside the retention window (about 24 to 72 hours).

Q: CDC or Platform Events? When do you choose which? A: CDC when you want to react to record changes with no publishing code, it auto-fires on create/update/delete/undelete. Platform Events when you need a custom business signal with your own schema, published deliberately from Apex, Flow, or an external system.

Talking point to explain it to anyone: "Stop hitting refresh on your inbox. This is the notification that pops the second mail arrives. The change comes to you."

7. Key terms

Change Data Capture, Platform Event, event bus, Pub/Sub API, lightning/empApi, CometD, replay ID, retention window - defined in Module 01 vocabulary and the README.

Sources (Verified June 2026)

• UI Update Based on Data Changes - Integration Patterns and Practices (v66.0, Spring '26)
• Pub/Sub API - Get Started - Salesforce Developers
• lightning/empApi - Lightning Component Library
• Change Data Capture Developer Guide - Salesforce Developers
• Message Durability - Streaming API Developer Guide

Next: back to the README.md for the full pattern map. From here, continue to Module 03 - Authentication (already built, the auth behind every callout and external subscriber) and then Module 04 to keep going.

Module 03 - Authentication (Slow Down Here)

Goal: Stop being confused by OAuth. Pick the right flow without thinking, and be able to explain any of them to anyone. API version: v66.0 (Spring '26). Login host: always your My Domain.

This module is a complete, interview-ready reference for Salesforce authentication. Every OAuth flow gets its own file with a plain-English explanation, a Mermaid sequence diagram, real requests/responses, security pitfalls, and interview Q&A. Start with 01-authentication-fundamentals.md — it defines the tokens, scopes, and endpoints that every other file builds on.

How to use this module

1. Read 01-authentication-fundamentals.md once. It is the spine.
2. Walk the flows in order (02 → 12), or jump to the one you need via the table below.
3. Read the four ecosystem files (13 → 17) — these are the containers and surrounding plumbing interviewers love to probe.
4. Use the comparison table and decision tree below as your pre-interview cram sheet, plus the one-pager in ../12-Cheatsheets/oauth-flows.md.

Map of this module

The master comparison table (memorize this)

If you only revise one thing before the interview, revise this. Direction = who hosts the flow. User? = is a human interactively present. Refresh? = does it issue a refresh token.

Outbound (Salesforce → external) is a different question entirely: don't hand-code a flow, configure a Named Credential + External Credential.

The decision tree — "which flow do I use?"

Two flows are missing on purpose. User-Agent (03) and Username-Password (07) are legacy/retiring. If a question pushes you toward them, the correct answer is "use Web Server + PKCE or Client Credentials instead, here's why."

What changed in 2025-2026 (sound current)

• Username-Password flow is retiring (blocked by default for orgs created Summer '23+, full retirement targeted Winter '27). Migrate to Client Credentials or Web Server + PKCE.
• External Client Apps replace Connected Apps — new Connected App creation is disabled by default starting Spring '26 (rollout from Winter '26). Build new integrations on ECAs.
• Client Credentials is the recommended server-to-server flow, and PKCE is recommended for all interactive flows.
• Device Flow was removed from the auto-installed Data Loader connected app (Sept 2, 2025).

Rapid-fire cross-flow interview questions

Q: A backend job needs to sync data nightly, no user. Which flow? → Client Credentials (05) if secret-based, or JWT Bearer (04) if certificate-based. Never Username-Password.

Q: Which flows return a refresh token? → User-context flows: Web Server, Device, Auth Code & Credentials (and User-Agent optionally). Machine flows (JWT Bearer, Client Credentials, SAML Bearer) do not — you just re-run them.

Q: Salesforce needs to call an external REST API. What's the right pattern? → Named Credential + External Credential (14). Never hardcode tokens in Apex.

Q: What makes PKCE necessary? → Public clients can't keep a secret, so an intercepted auth code could be redeemed by an attacker. PKCE binds the code to a one-time verifier. See 02.

Q: Connected App or External Client App for a new build in 2026? → External Client App — Connected App creation is being disabled by default. See 13.

Sources (Verified June 2026)

• Authorize Apps with OAuth — Salesforce Help
• OAuth Authorization Flows — Salesforce Help
• External Client Apps and Connected Apps — Salesforce Help
• Retirement of OAuth 2.0 Username-Password Flow — Release Notes

Every per-file Sources section links the specific official doc for that flow.

01 - Authentication Fundamentals (Read This First)

Goal: Build the mental model that makes every OAuth flow click. If you understand the actors, tokens, scopes, and endpoints here, the 11 flows are just different ways of getting the same access token. API version: v66.0 (Spring '26). Login host: always your My Domain (https://MyDomainName.my.salesforce.com).

This is the shared vocabulary for Module 03. Every flow file links back here instead of re-explaining tokens and scopes.

1. AuthN vs AuthZ (the distinction interviewers test first)

Two different questions, two different words people lazily merge into "auth":

One-line answer for an interview: "Authentication proves identity; authorization grants permission. OAuth 2.0 is primarily an authorization framework. OpenID Connect is the thin authentication layer added on top of OAuth, and in Salesforce it shows up as the ID token and the openid scope."

2. The cast of characters (the 5 roles)

Every flow is a conversation between these roles. Learn the roles once and you can read any sequence diagram.

Note: In Salesforce the Authorization Server and Resource Server are the same platform, just different endpoints. That is why your access token works against the API immediately, with no extra exchange.

3. The three tokens (know these cold)

99% of "what does this flow return?" questions come down to these three strings.

Interview trap: "Does the JWT Bearer flow return a refresh token?" No. Certificate-based machine flows (JWT Bearer, Client Credentials) return an access token only — there is no user session to keep alive, so you just re-run the flow to get a fresh token. See 04-jwt-bearer-flow.md and 05-client-credentials-flow.md.

4. Scopes (what the token is allowed to touch)

A scope is a permission string you request when getting a token. Salesforce only grants scopes the Connected App / External Client App has been configured to allow.

Least privilege rule: request only what you need. For a typical server integration, api refresh_token is enough. Asking for full on a backend job is a red flag in a security review.

Gotcha: Even when you request full, you still must explicitly request refresh_token (or offline_access) to get a refresh token. This catches people constantly.

5. The OAuth 2.0 endpoints (one base, five doors)

All endpoints live under your My Domain host. Replace MyDomainName with your org's My Domain. (You can still see login.salesforce.com in old docs, but My Domain is the correct, future-proof host and is mandatory for many flows.)

Base: https://MyDomainName.my.salesforce.com/services/oauth2/

Test vs prod: sandboxes use https://MyDomainName--SandboxName.sandbox.my.salesforce.com. The legacy test.salesforce.com host maps to sandboxes; login.salesforce.com to production. Prefer My Domain everywhere.

6. My Domain — why every flow says "use your My Domain"

My Domain is your org's unique login subdomain (e.g. acme.my.salesforce.com). Since Spring '23 it is mandatory for all production orgs. It matters for auth because:

1. It is the issuer of your tokens — external IdPs and partners pin to it.
2. Enhanced Domains changed the URL format; old hardcoded *.salesforce.com hostnames break. Always build URLs from My Domain.
3. SSO, branded login pages, and many newer flows (Client Credentials, Auth Code & Credentials) require My Domain.

7. The container: Connected App vs External Client App

Every OAuth flow needs a registered app definition that holds the client id (a.k.a. consumer key), client secret (consumer secret), allowed scopes, callback URL, and which flows are enabled.

• Connected App — the original container (2013+). Being phased out for new creation: Salesforce disabled creating new Connected Apps by default starting Winter '26 / Spring '26.
• External Client App (ECA) — the next generation (GA 2024+). Separates developer OAuth config from admin policy, is built for 2GP packaging, and is the go-forward choice.

Full comparison, including which flows each supports, is in 13-connected-apps-vs-external-client-apps.md. For now: the app is the door; the flow is how you walk through it.

8. What changed in 2025-2026 (say this and you sound current)

Interviewers reward candidates who know the platform is moving. The three headlines:

9. grant_type cheat table (map flow → token request)

When you POST to /services/oauth2/token, the grant_type parameter tells Salesforce which flow you're running. Memorize this table and you can identify any flow from a raw HTTP request.

10. Glossary (quick definitions)

• Bearer token — any token where possession = access. Whoever holds it can use it, so it must be protected like a password.
• Consumer Key / Client ID — public identifier of your app.
• Consumer Secret / Client Secret — private password of your app. Confidential clients can keep it; public clients (mobile, SPA) cannot.
• Confidential client — an app that can store a secret safely (a backend server).
• Public client — an app that cannot keep a secret (mobile app, single-page app). Uses PKCE instead.
• PKCE ("pixie") — Proof Key for Code Exchange. Adds a one-time code_verifier/code_challenge pair so an intercepted auth code is useless. See 02-web-server-flow.md.
• Callback URL / Redirect URI — where Salesforce sends the browser back after login. Must match the app config exactly.
• JWT — JSON Web Token. A signed, self-contained token: header.payload.signature, base64url-encoded.
• Assertion — a signed statement (JWT or SAML) that the token endpoint trusts in place of interactive login.
• Identity URL — a Salesforce URL unique to each user that returns profile info; delivered with the access token.
• Named Principal vs Per-User — whether one shared identity or each user's own identity is used for an outbound callout. See 14-named-credentials-and-external-credentials.md.
• frontdoor.jsp — Salesforce URL that turns a valid access token into a browser UI session (needs web scope).

Sources (Verified June 2026)

• OAuth Tokens and Scopes — Salesforce Help
• Authorize Apps with OAuth — Salesforce Help
• OAuth Endpoints — Salesforce Help
• OpenID Connect Token Introspection Endpoint — Salesforce Help
• External Client Apps and Connected Apps — Salesforce Help
• Retirement of OAuth 2.0 Username-Password Flow — Release Notes
• My Domain — Salesforce Help

Next: 02-web-server-flow.md — the most common flow, used whenever a real user logs in to a web app.

02 - Web Server Flow (Authorization Code) + PKCE

One-liner: A real user clicks "Log in with Salesforce," approves access, and your backend server exchanges a short-lived code for tokens. Use when: A web app with a server backend acts on behalf of a logged-in user. Grant type: authorization_code · Status: ✅ Recommended (the gold standard for user login). Tokens returned: Access token + refresh token (+ ID token if openid).

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

Think of a hotel. You (the user) show your ID at the front desk (Salesforce login). The desk doesn't hand your passport to the bellhop — it gives the bellhop (your app) a key card (access token) that opens only certain doors (scopes), for a limited time.

The clever part: the front desk first gives a claim ticket (authorization code) to the user's browser, and your server quietly trades that ticket for the real key card over a back channel. The browser never sees the access token, and the server proves its identity with a secret. That two-step "code then token" exchange is what makes this the most secure interactive flow.

2. When to use it (and when not)

Real-world examples: a customer portal built in Node/Java that reads the user's Salesforce records; a marketing tool where each user connects their own Salesforce; "Log in with Salesforce" on a third-party SaaS.

3. How it works (sequence diagram)

Walkthrough

1-2. App sends the user's browser to the authorize endpoint with its client_id, the redirect_uri, requested scope, and a random state (CSRF guard). 3-5. Salesforce authenticates the user (password, MFA, or SSO) and shows a one-time consent screen. 6-7. Salesforce redirects the browser back to your redirect_uri with a short-lived authorization code (valid ~15 min, single use). 8. Your server (not the browser) POSTs the code plus its client_secret to the token endpoint. 9. Salesforce returns the access token, a refresh token, and instance_url. 10-11. Your app calls the API with Authorization: Bearer <access_token>.

4. PKCE — the mandatory upgrade for public clients

PKCE (Proof Key for Code Exchange, say "pixie", RFC 7636) defends against someone stealing the authorization code in transit. The app generates a random secret per login and proves it owns that secret when redeeming the code.

Why it matters: a stolen code is useless without the matching code_verifier, which never left the app. Salesforce recommends PKCE for all clients and it is effectively required for mobile/SPA. Add two params to the authorize request (code_challenge, code_challenge_method=S256) and one to the token request (code_verifier).

5. The actual requests & responses

Step 1 — send the browser here (authorize):

https://MyDomainName.my.salesforce.com/services/oauth2/authorize
  ?response_type=code
  &client_id=3MVG9...CONSUMER_KEY
  &redirect_uri=https://app.example.com/oauth/callback
  &scope=api%20refresh_token%20openid
  &state=xyz123
  &code_challenge=Psd... (PKCE)
  &code_challenge_method=S256

Step 2 — Salesforce redirects back:

https://app.example.com/oauth/callback?code=aPrx...AUTH_CODE&state=xyz123

Step 3 — exchange the code (token), server-side:

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -d grant_type=authorization_code \
  -d code=aPrx...AUTH_CODE \
  -d client_id=3MVG9...CONSUMER_KEY \
  -d client_secret=ABCD...CONSUMER_SECRET \
  -d redirect_uri=https://app.example.com/oauth/callback \
  -d code_verifier=THE_ORIGINAL_RANDOM_STRING

Step 4 — the token response:

{
  "access_token": "00D5g000004...!AQEAQ...",
  "refresh_token": "5Aep861...l4Lo",
  "signature": "k0r...=",
  "scope": "api refresh_token openid",
  "id_token": "eyJraWQiOiI...",
  "instance_url": "https://MyDomainName.my.salesforce.com",
  "id": "https://login.salesforce.com/id/00D.../005...",
  "token_type": "Bearer",
  "issued_at": "1718700000000"
}

Connected App / ECA setup checklist

1. Create a Connected App (or External Client App — preferred). Enable OAuth Settings.
2. Set the Callback URL to exactly your redirect_uri.
3. Select scopes (e.g. Access and manage your data (api), Perform requests at any time (refresh_token, offline_access)).
4. Keep "Require Proof Key for Code Exchange (PKCE)" checked.
5. Copy the Consumer Key (client_id) and Consumer Secret (client_secret).
6. Optionally set IP relaxation, refresh-token policy, and permitted users.

Salesforce as the client (outbound): when Salesforce itself needs to call an external API on behalf of each user, you don't hand-code this flow — you configure a Named Credential with an External Credential of type "OAuth 2.0 — Authorization Code" (Browser Flow). Salesforce runs steps 1-9 for you. See 14-named-credentials-and-external-credentials.md.

6. Security pitfalls & gotchas

7. Interview Q&A

Q: Walk me through the Authorization Code flow. A: App redirects the user's browser to /authorize; user logs in and consents; Salesforce returns a short-lived auth code to the registered callback; the app's server exchanges that code plus its client secret at /token for an access token and refresh token; the app calls the API with the bearer token. The browser never sees the access token.

Q: Why two steps — code then token? Why not return the token directly? A: Returning the token directly (the old User-Agent / implicit flow) exposes it in the browser URL/history where it can leak. The code-then-token split keeps the access token on a secure back channel, authenticated by the client secret.

Q: What is PKCE and what attack does it stop? A: Proof Key for Code Exchange. The app sends a hashed code_challenge up front and the raw code_verifier at redemption. It stops authorization-code interception — a stolen code is useless without the verifier. Required for public clients, recommended for all.

Q: Difference between this and Client Credentials / JWT Bearer? A: Web Server flow is user-context (acts as the logged-in user, returns a refresh token). Client Credentials and JWT Bearer are system-context (no user, no refresh token), for backend integrations.

Q: The access token expired mid-session. What happens? A: API returns 401 INVALID_SESSION_ID. The app silently calls /token with grant_type=refresh_token to get a new access token — no user interaction. See 08-refresh-token-flow.md.

Talking point to explain it to anyone: "It's a coat check. You show ID once, get a claim ticket, and your app swaps the ticket for a key that opens just the doors it needs, for a while."

8. Key terms

authorization_code · state · code_challenge / code_verifier · redirect_uri · confidential vs public client — all defined in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• OAuth 2.0 Web Server Flow for Web App Integration — Salesforce Help
• Implement the OAuth 2.0 Web Server Flow — Trailhead
• OAuth Tokens and Scopes — Salesforce Help
• PKCE (RFC 7636)

Next: 03-user-agent-flow.md — the older browser-only flow this one replaced.

03 - User-Agent Flow (Browser Implicit-Style)

One-liner: A browser-based app sends the user to Salesforce to log in, and the access token comes straight back in the URL fragment (#access_token=...) for the browser to read. Use when: (Historically) a mobile, desktop, or JavaScript app with no server backend to keep a secret. Today, prefer the Web Server flow + PKCE instead. Grant type: response_type=token (OAuth 2.0 implicit grant) · Status: ⚠️ Legacy — Salesforce recommends 02-web-server-flow.md + PKCE instead. Tokens returned: Access token (+ optional refresh token) delivered in the URL fragment. No client secret used (public client).

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

Imagine a valet stand that hands the car key directly to whoever is standing at the booth. The user walks up (their browser), proves who they are, and Salesforce tosses the key (access token) straight back onto the counter where the browser can grab it. There is no back office, no second handshake, no secret password the app whispers to prove it is trustworthy.

That speed is also the weakness. Because the token lands in the browser's address bar (after the #), it can leak into browser history, server logs, and Referer headers. The newer Web Server flow fixes this by handing over a one-time claim ticket (auth code) instead and swapping it for the real token on a private back channel. That is why Salesforce now steers everyone to Web Server + PKCE.

2. When to use it (and when not)

Reality check: Salesforce Mobile SDK used this flow through version 10.2, then switched its default to the Web Server flow with PKCE in Mobile SDK 11.0. Salesforce explicitly calls the user-agent flow insecure and recommends blocking it for new integrations. Treat any new request to use it as a red flag in a design review.

Real-world examples (legacy): an old single-page dashboard that read Salesforce data directly from JavaScript; an early native mobile app before PKCE existed; a quick internal tool that grabbed a token in the browser.

3. How it works (sequence diagram)

Walkthrough

1. The app sends the user's browser to the authorize endpoint with response_type=token, its client_id, the redirect_uri, requested scope, and a random state (CSRF guard). 2-3. Salesforce authenticates the user (password, MFA, or SSO) and shows the consent screen.
2. Salesforce redirects the browser back to the redirect_uri with the access token in the URL fragment (after #), not as a query parameter. The fragment is never sent to a server, so it stays in the browser.
3. The app's JavaScript reads the token from window.location.hash. Best practice: immediately call window.location.replace() to strip the token out of browser history. 6-7. The app calls the API directly with Authorization: Bearer <access_token>.

Why the fragment (#) and not a query (?): the part of a URL after # is never transmitted to the web server and is omitted from Referer headers. Salesforce deliberately uses the fragment so the token is not leaked to your callback server or to downstream sites. It still ends up exposed to the browser and any script on the page, which is the core security problem.

4. The actual requests & responses

Step 1 — send the browser here (authorize):

https://MyDomainName.my.salesforce.com/services/oauth2/authorize
  ?response_type=token
  &client_id=3MVG9...CONSUMER_KEY
  &redirect_uri=https://app.example.com/oauth/callback
  &scope=api%20web
  &state=xyz123

Step 2 — Salesforce redirects back with the token in the fragment:

https://app.example.com/oauth/callback#access_token=00D5g000004...!AQEAQ...
  &instance_url=https%3A%2F%2FMyDomainName.my.salesforce.com
  &id=https%3A%2F%2Flogin.salesforce.com%2Fid%2F00D...%2F005...
  &issued_at=1718700000000
  &signature=k0r...%3D
  &scope=api+web
  &token_type=Bearer
  &state=xyz123

There is no curl token exchange step here. Unlike the Web Server flow, the app does not POST to /services/oauth2/token. The token is already in the redirect. The browser parses the fragment client-side:

// Read the access token from the URL fragment
const params = new URLSearchParams(window.location.hash.substring(1));
const accessToken = params.get('access_token');
const instanceUrl = params.get('instance_url');

// Immediately remove the token from history (recommended by Salesforce)
window.location.replace('/app-home');

Connected App / ECA setup checklist

1. Create a Connected App (or External Client App). Enable OAuth Settings.
2. Set the Callback URL to exactly your redirect_uri.
3. Select scopes. For the user-agent flow you typically need api and web. Add refresh_token / offline_access only if you intend to receive a refresh token (and accept that storing it in a browser is risky).
4. Because this is a public client, the Consumer Secret is not sent. Do not embed it in client code.
5. Strongly consider enabling "Require Proof Key for Code Exchange (PKCE)" and migrating to the Web Server flow instead.

Hybrid alternative: Salesforce also documents a Hybrid User-Agent Token flow, which starts like the user-agent flow but returns an authorization code you can exchange for a refresh token on a back channel. It exists specifically to give browser apps a safer path to long-lived access. If you are stuck on a browser-only architecture, evaluate it before the raw user-agent flow.

5. Security pitfalls & gotchas

6. Interview Q&A

Q: What is the User-Agent flow and how does it differ from the Web Server flow? A: It is the OAuth 2.0 implicit grant (response_type=token). Salesforce returns the access token directly in the redirect URL fragment to the browser. The Web Server flow instead returns a one-time authorization code that the server exchanges for tokens on a back channel. User-Agent skips that second step, so it is simpler but less secure.

Q: Why is the token returned in the fragment (#) instead of a query string (?)? A: The fragment is never sent to the server and is excluded from Referer headers, so it does not leak to your callback host or downstream sites. It is still visible to the browser and page scripts, which is why the flow is discouraged.

Q: Why does Salesforce now discourage this flow? A: The token is exposed in the browser URL, history, and to any script on the page. There is no back channel and no client secret, so a stolen token is immediately usable. Salesforce recommends Web Server flow + PKCE, and Mobile SDK switched its default to that in version 11.0.

Q: Does the User-Agent flow use a client secret? A: No. It is a public client flow. Client executables and browser code cannot keep a secret safely, so the flow is designed without one. Anyone shipping a secret in client code has a vulnerability.

Q: A mobile app needs to log a user in today. Should it use the User-Agent flow? A: No. Use the Web Server flow in public-client mode with PKCE. It gives the same "no secret" benefit but keeps the token off the URL and protects the code exchange with a one-time verifier.

Talking point to explain it to anyone: "It is like a valet who hands the car key straight to whoever is at the booth. Fast, but anyone watching the counter can grab the key. The newer flow gives you a claim ticket instead and fetches the key in the back office."

7. Key terms

response_type=token · implicit grant · URL fragment · public client · state · PKCE — all defined in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• OAuth 2.0 User-Agent Flow for Desktop or Mobile App Integration — Salesforce Help
• OAuth 2.0 User-Agent Flow — Mobile SDK Development Guide
• OAuth 2.0 Hybrid User-Agent Token Flow for Web Session Management — Salesforce Help
• Block Authorization Flows to Improve Security — Salesforce Help
• OAuth 2.0 Implicit Grant (RFC 6749 §4.2)

Next: 04-jwt-bearer-flow.md — the certificate-signed server-to-server flow that needs no user and no password.

04 - JWT Bearer Token Flow

One-liner: A backend app proves its identity with a private key (no password, no browser) by signing a short-lived JWT that Salesforce verifies against an uploaded certificate. Use when: Server-to-server / CI-CD where a trusted backend acts as a pre-authorized user with zero human interaction. Grant type: urn:ietf:params:oauth:grant-type:jwt-bearer · Status: ✅ Recommended (the classic machine flow; great when you can manage a key pair). Tokens returned: Access token only. No refresh token (you just re-sign a new JWT).

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

Think of a wax seal on a letter. Long ago, a noble pressed a signet ring into hot wax. Anyone holding the matching seal-stamp on file could look at the wax and say "yes, this really came from that noble." Nobody had to mail the ring itself.

Here your app is the noble. The private key is the signet ring. The X.509 certificate uploaded to the Connected App is the seal-stamp Salesforce keeps on file. Each time the app wants a token, it writes a tiny note (the JWT) that says "I am app X, acting as user Y, and this note is valid for the next 3 minutes," then presses its private-key ring into it. Salesforce checks the seal against the certificate, sees the user was already pre-approved, and hands back an access token. The private key never leaves your server. There is no password to steal and no browser to redirect.

2. When to use it (and when not)

Real-world examples: a nightly Java/Node ETL job syncing an ERP into Salesforce; a Jenkins/GitHub Actions pipeline running sf project deploy; a middleware tier that acts as one fixed integration user across all calls.

Interview trap: "Does JWT Bearer return a refresh token?" No. There is no user session to keep alive, so when the access token expires you simply sign a fresh JWT and ask again. Same answer for Client Credentials.

3. How it works (sequence diagram)

Walkthrough

1-2. The app assembles the JWT claims and signs the token with its private key using RS256. 3. The app POSTs to the token endpoint with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer and the JWT in the assertion parameter. 4-5. Salesforce verifies the signature against the X.509 certificate stored on the Connected App / External Client App, confirms the sub user is pre-authorized, and checks that exp is still in the future. 6. Salesforce returns an access token and instance_url. No refresh token is issued. 7-8. The app calls the API with Authorization: Bearer <access_token>.

4. The JWT — header, claims, signature

A JWT is three base64url parts joined by dots: header.payload.signature.

Header (algorithm is fixed to RS256):

{ "alg": "RS256" }

Claims (payload) — the four that matter:

Sample claims set:

{
  "iss": "3MVG9...CONSUMER_KEY",
  "sub": "integration@acme.com",
  "aud": "https://login.salesforce.com",
  "exp": 1718700300
}

Notes: You cannot request scopes in this flow. Scopes come from the app's Permitted Users policy and the org's API Access Control settings. The jti (JWT ID) claim is optional, but if you include it Salesforce checks it has not been seen before, which blocks replay attacks. Keep exp short (the platform's own External Credentials default is 2 minutes, and signed JWTs are typically set to 3-5 minutes).

5. The actual requests & responses

Step 1 — generate a key pair and self-signed certificate (OpenSSL):

# 2048-bit RSA private key (keep this secret, never commit it)
openssl genrsa -out server.key 2048

# Certificate signing request
openssl req -new -key server.key -out server.csr

# Self-signed X.509 certificate, valid 1 year (upload server.crt to Salesforce)
openssl x509 -req -sha256 -days 365 -in server.csr -signkey server.key -out server.crt

server.key = the private key your app signs with. server.crt = the public certificate (must be ≤ 4 KB) you upload to the Connected App.

Step 2 — Connected App / ECA setup checklist:

1. Create a Connected App (or External Client App — preferred). Enable OAuth Settings.
2. Check "Use digital signatures" and upload server.crt.
3. Select OAuth scopes (e.g. api, refresh_token is irrelevant here). A callback URL is required by the form but unused by this flow.
4. Copy the Consumer Key (this becomes iss / client_id).
5. Under the app's policies, set Permitted Users = "Admin approved users are pre-authorized" and assign the run-as user via a profile or permission set. This is what makes the sub user allowed.

Step 3 — exchange the signed JWT for a token:

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  -d assertion=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiIzTVZHOS4uLiJ9.SIGNATURE

Step 4 — the token response (no refresh token):

{
  "access_token": "00D5g000004...!AQEAQ...",
  "scope": "api",
  "instance_url": "https://MyDomainName.my.salesforce.com",
  "id": "https://login.salesforce.com/id/00D.../005...",
  "token_type": "Bearer"
}

Step 5 — the Salesforce CLI does all of this for you (the CLI's org login jwt is the JWT Bearer flow):

sf org login jwt \
  --client-id 3MVG9...CONSUMER_KEY \
  --jwt-key-file ./server.key \
  --username integration@acme.com \
  --instance-url https://MyDomainName.my.salesforce.com \
  --alias ci-org --set-default

--client-id (the consumer key), --jwt-key-file (your server.key), and --username (the run-as user) are required. Use --instance-url for My Domain or a sandbox host. This is the standard way to authorize an org in CI/CD where no browser is available.

Salesforce as the client (outbound): when Salesforce itself calls an external system using a JWT, you don't hand-sign tokens — you configure a Named Credential with an External Credential of type "OAuth 2.0 — JWT Bearer" and edit the JWT claims (iss, sub, aud, exp) in the UI. See 14-named-credentials-and-external-credentials.md.

6. Security pitfalls & gotchas

7. Interview Q&A

Q: Walk me through the JWT Bearer flow. A: The app builds a JWT with claims iss (client_id), sub (run-as username), aud (login host), and a short exp, signs it with its private key (RS256), and POSTs it to /services/oauth2/token as the assertion with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer. Salesforce verifies the signature against the uploaded X.509 certificate, confirms the sub user is pre-authorized, and returns an access token only.

Q: Why no refresh token? A: There is no interactive user session to keep alive. The app already holds the private key, so getting a fresh access token is as cheap as signing a new JWT. Refresh tokens exist to avoid re-prompting a human — irrelevant here.

Q: How does Salesforce trust the JWT without a password? A: Asymmetric crypto. The app signs with the private key; Salesforce holds only the matching public certificate. A valid signature proves the holder of the private key produced it, and the sub user was pre-approved on the Connected App.

Q: What does each claim do, and what is aud? A: iss = your Consumer Key, sub = the user to run as, exp = short expiry, and aud = the intended recipient, i.e. the Salesforce login host (login/test/My Domain). A mismatched aud is the most common reason the flow fails between sandbox and prod.

Q: JWT Bearer vs Client Credentials — when do you pick which? A: Both are passwordless server-to-server with no refresh token. JWT Bearer uses a key pair and impersonates a named sub user (and powers the CLI). Client Credentials uses a client secret and a configured run-as user with no JWT to build. If you already manage certificates or use the CLI, JWT; if you want the simplest secret-based setup, Client Credentials. See 05-client-credentials-flow.md.

Q: How does sf org login jwt relate to this flow? A: It is this flow. You pass --client-id, --jwt-key-file, and --username; the CLI signs the JWT and exchanges it. It is the standard headless auth for CI/CD.

Talking point to explain it to anyone: "It's a wax seal. Your server presses its private-key ring into a short note, Salesforce checks the seal against the stamp it has on file, and lets it in. No password ever travels."

8. Key terms

urn:ietf:params:oauth:grant-type:jwt-bearer · JWT (header.payload.signature) · assertion · iss / sub / aud / exp · X.509 certificate · private key · pre-authorized user · confidential client — all defined in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• OAuth 2.0 JWT Bearer Flow for Server-to-Server Integration — Salesforce Help
• Authorize an Org Using the JWT Flow — Salesforce DX Developer Guide
• org login jwt — Salesforce CLI Command Reference
• Create a Private Key and Self-Signed Digital Certificate — Salesforce DX Developer Guide
• OAuth 2.0 Bearer Flow JWT Claims — Named Credentials Reference

Next: 05-client-credentials-flow.md — the secret-based server-to-server flow that runs as a fixed integration user.

05 - Client Credentials Flow

One-liner: A backend app trades only its client id + secret for an access token that runs as a pre-configured integration user — no JWT, no user login. Use when: Server-to-server integration with no user context that always runs as the same fixed identity. Grant type: client_credentials · Status: ✅ Recommended (the modern replacement for the retiring Username-Password flow). Tokens returned: Access token only. No refresh token, no user login.

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

Think of a vending-machine service key. A maintenance company isn't a person — it's a company. But the machine still needs to know "who" opened it. So the building gives the company one master key tied to a single named contractor account on file. Any technician using that key acts as that one contractor, with exactly the access that contractor was granted. No personal logins, no passwords passed around — just the key, and a fixed identity behind it.

Here your app presents its client id + client secret (the master key). Salesforce maps the request to the run-as integration user you configured on the Connected App (the contractor on file) and hands back an access token that has precisely that user's permissions. There is no human, no browser, and no JWT to build — it is the simplest passwordless server-to-server flow Salesforce offers.

2. When to use it (and when not)

Real-world examples: an ERP nightly sync running as a dedicated "ERP Integration" user; a data-warehouse extractor; a monitoring service polling records; any system-to-system job that the org wants attributed to a single, auditable service identity.

Why this is the new default: it needs no password and no key pair — just a secret and a configured run-as user. Salesforce positions it as the go-to server-to-server flow as the Username-Password flow retires (blocked by default for newer orgs, full retirement targeted Winter '27). See 07-username-password-flow.md.

3. How it works (sequence diagram)

Walkthrough

1. The app POSTs to the token endpoint (on your My Domain host) with grant_type=client_credentials plus its client_id and client_secret.
2. Salesforce validates the secret and resolves the run-as integration user configured on the app.
3. Salesforce returns an access token and instance_url. No refresh token. 4-5. The app calls the API; every call executes with the run-as user's profile, permission sets, and data access.

4. The actual requests & responses

My Domain is mandatory. login.salesforce.com and test.salesforce.com are not supported for this flow. The token endpoint must be https://MyDomainName.my.salesforce.com/services/oauth2/token (or your Experience Cloud domain).

Option A — credentials in the POST body:

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -d grant_type=client_credentials \
  -d client_id=3MVG9...CONSUMER_KEY \
  -d client_secret=ABCD...CONSUMER_SECRET

Option B — credentials as HTTP Basic auth (base64 of client_id:client_secret):

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -H "Authorization: Basic MzMVG9...base64(client_id:client_secret)" \
  -d grant_type=client_credentials

The token response (no refresh token):

{
  "access_token": "00D5g000004...!AQEAQ...",
  "signature": "k0r...=",
  "scope": "api",
  "instance_url": "https://MyDomainName.my.salesforce.com",
  "id": "https://login.salesforce.com/id/00D.../005...",
  "token_type": "Bearer",
  "issued_at": "1718700000000"
}

Connected App / ECA setup checklist

1. Create a Connected App (or External Client App — preferred) and enable OAuth Settings.
2. Check "Enable Client Credentials Flow."
3. Select the scopes you need — for pure API access, api is enough (least privilege).
4. Copy the Consumer Key and Consumer Secret (via Manage Consumer Details).
5. Open the app's Manage view → Edit Policies. Set Permitted Users = Admin Pre-Approved and choose the "Run-As User for the client credentials flow."
6. Assign the run-as user (via profile or permission set) so they are permitted to use the app.

The recommended run-as identity — the modern best practice from Salesforce:

• Create a dedicated user on the Salesforce Integration user license with the Minimum Access – API Only Integrations profile (enables API, restricts to API only).
• Grant exactly the data/operations needed via a permission set using the Salesforce API Integration permission set license (PSL).
• One app + one integration user per integration, so access is scoped, auditable, and the secret can be rotated affecting only that one integration.

It acts as the integration user, not the caller. Every action runs as the configured run-as user. If you pick a System Administrator, the token gets admin power — so scope it down hard.

5. Security pitfalls & gotchas

6. Interview Q&A

Q: What is the Client Credentials flow and when is it the right choice? A: A server-to-server OAuth flow where the app exchanges just its client id and secret for an access token, with no user interaction and no refresh token. It's the right choice for headless integrations that always run as the same fixed identity — backups, analytics, ETL — and it's the modern replacement for the Username-Password flow.

Q: Whose permissions does the token have? A: The run-as integration user configured on the Connected App's policies — not the caller. Best practice is a dedicated user on the Integration user license with the Minimum Access – API Only Integrations profile, scoped by a permission set with the API Integration PSL.

Q: Why does Salesforce force you to pick a run-as user for a "userless" flow? A: Everything in Salesforce executes in a user context for sharing, FLS, and auditing. Even a system integration must map to a user so its actions are attributable and its data access is governed.

Q: Client Credentials vs JWT Bearer — compare them. A: Both are passwordless, server-to-server, and return no refresh token. Client Credentials uses a client secret and a configured run-as user — simplest setup, no JWT. JWT Bearer uses a private key and names the user in the JWT's sub, and it powers the Salesforce CLI. Pick Client Credentials for the simplest secret-based service identity; JWT when you already manage certificates. See 04-jwt-bearer-flow.md.

Q: Why is My Domain required here? A: The flow is explicitly not supported on login.salesforce.com / test.salesforce.com. Salesforce ties the integration to your org's branded, stable issuer host, so you must call the My Domain token endpoint.

Q: How do you handle token expiry? A: There is no refresh token, so when a call returns 401, you simply re-run the Client Credentials request with the same id and secret to get a fresh access token. If using JWT-based access tokens, you can also inspect the exp claim locally and refresh proactively.

Talking point to explain it to anyone: "It's a service master key tied to one named maintenance account. The app shows the key, Salesforce knows exactly which limited account it stands for, and grants only that account's access — no personal passwords involved."

7. Key terms

client_credentials · run-as user · integration user · Integration user license · Minimum Access – API Only Integrations profile · API Integration PSL · client secret · least privilege · My Domain — all defined in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• OAuth 2.0 Client Credentials Flow for Server-to-Server Integration — Salesforce Help
• Configure a Connected App for the OAuth 2.0 Client Credentials Flow — Salesforce Help
• Invoke REST APIs with the Salesforce Integration User and OAuth Client Credentials — Salesforce Developers Blog
• Using the Client Credentials Flow for Easier API Authentication — Salesforce Developers Blog
• Give Integration Users API Only Access — Salesforce Help

Next: 06-device-flow.md — authorizing input-constrained devices (TVs, CLIs) with a user code.

06 - OAuth 2.0 Device Flow

One-liner: A device with no keyboard or browser (smart TV, CLI, IoT box) shows the user a short code and a URL. The user opens that URL on their phone, types the code, and the device gets a token. Use when: An app runs on hardware with limited input or display that cannot host a full login page. Grant type: response_type=device_code (start), then grant_type=device (poll) · Status: ✅ Supported, but input-constrained devices only. Removed from the auto-installed Data Loader connected app on Sept 2, 2025. Tokens returned: Access token (+ refresh token if refresh_token/offline_access scope requested).

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

Think of signing in to a streaming app on a new smart TV. The TV cannot show a comfortable login form, and typing your password with a remote is painful. So the TV puts up a message: "Go to example.com/activate and enter code WDJB-MJHT." You pull out your phone, open that page, log in there once, type the short code, and approve. The TV, meanwhile, keeps quietly asking Salesforce "are we approved yet?" every few seconds until you finish. Then it gets its token.

That split is the whole flow. The constrained device never handles the password. All the typing and authentication happen on a second screen (your phone or laptop) that already has a real browser. The device just polls and waits.

2. When to use it (and when not)

Real-world examples: a Salesforce dashboard on a wall-mounted smart display in a sales bullpen; a command-line data tool that asks you to approve on your laptop; an IoT gateway that posts telemetry as a specific Salesforce user.

Heads up — Data Loader change: Salesforce removed OAuth 2.0 Device Flow support from the auto-installed Data Loader connected app on September 2, 2025. Data Loader v53.0.1 introduced device-flow login, but newer Data Loader (e.g. v64.1.0) no longer supports Device Flow (or User-Agent Flow). The Salesforce CLI's default connected app saw a similar device-flow removal in 2025. If a tool used to log in with a device code and suddenly fails, this is a likely cause. Migrate to the Web Server flow or use a dedicated connected app.

3. How it works (sequence diagram)

Walkthrough

1-2. Device requests a code. The device POSTs to the token endpoint with response_type=device_code and its client_id. Salesforce returns a device_code (the device's secret handle), a short user_code for the human to type, a verification_uri to visit, a expires_in lifetime, and a polling interval in seconds. 3. Device shows instructions. It displays the user_code and verification_uri on screen (e.g. "Visit ...activate and enter WDJB-MJHT"). 4-5. Device polls. Starting now, the device POSTs to the token endpoint with grant_type=device and code=<device_code> every interval seconds. Until the user approves, Salesforce replies authorization_pending. 6. User approves on a second screen. On a phone or laptop, the user opens the verification_uri, authenticates (password, MFA, SSO), enters the user_code, and grants consent. 7-8. Device receives tokens. The next poll succeeds: Salesforce returns the access token, optionally a refresh token, and instance_url. The device calls the API with the bearer token.

4. The actual requests & responses

Step 1 — device asks for a code:

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -d response_type=device_code \
  -d client_id=3MVG9...CONSUMER_KEY \
  -d scope=api%20refresh_token

Step 1 response — what the device shows the user:

{
  "device_code": "GmRhmhcxhw...EUqIVDf0",
  "user_code": "WDJBMJHT",
  "verification_uri": "https://MyDomainName.my.salesforce.com/setup/connect",
  "interval": 5,
  "expires_in": 600
}

Step 2 — the user goes to verification_uri on a phone/PC, logs in, and enters user_code. (No code on the device side for this step; it is a human action in a browser.)

Step 3 — device polls the token endpoint at the given interval:

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -d grant_type=device \
  -d client_id=3MVG9...CONSUMER_KEY \
  -d code=GmRhmhcxhw...EUqIVDf0

Step 3 response while waiting (HTTP 400, keep polling):

{ "error": "authorization_pending", "error_description": "User has not yet approved the device." }

Step 3 response once approved (HTTP 200):

{
  "access_token": "00D5g000004...!AQEAQ...",
  "refresh_token": "5Aep861...l4Lo",
  "signature": "k0r...=",
  "scope": "api refresh_token",
  "instance_url": "https://MyDomainName.my.salesforce.com",
  "id": "https://login.salesforce.com/id/00D.../005...",
  "token_type": "Bearer",
  "issued_at": "1718700000000"
}

Connected App / ECA setup checklist

1. Create a Connected App (or External Client App). Enable OAuth Settings.
2. Enable the device flow. For a Connected App, turn on the device-flow option in Global / OAuth settings (the setting that lets the app issue a device code). For an External Client App, enable the device flow policy (the isDeviceFlowEnabled setting).
3. Select scopes (api, plus refresh_token/offline_access if you want a refresh token).
4. A callback URL is not used by the device flow itself, but the app still requires one configured.
5. Copy the Consumer Key (client_id). The device flow is for public clients; do not rely on shipping a secret to the device.

5. Security pitfalls & gotchas

Interview-grade nuance: device-flow phishing is the same class of attack that hit large numbers of Microsoft 365 tenants. The danger is that the login page is 100% genuine — there is no lookalike domain to flag — so the only real defense is user awareness plus scope and consent controls. Expect this as a security question.

6. Interview Q&A

Q: When would you choose the Device Flow? A: When the app runs on hardware with limited input or display that cannot present a normal login page: smart TVs, set-top boxes, appliances, IoT devices, and headless CLI tools. The user authenticates on a second device with a real browser.

Q: Walk me through the steps. A: The device POSTs response_type=device_code with its client_id and gets back a device_code, a human-friendly user_code, a verification_uri, an interval, and expires_in. It shows the user the code and URL, then polls the token endpoint with grant_type=device and code=<device_code> every interval seconds. The user opens the URL on a phone, logs in, enters the code, and approves. The next poll returns the access token (and refresh token if requested).

Q: What is device-code phishing and how do you defend against it? A: An attacker starts their own device flow, obtains a legitimate user_code, and socially engineers a victim into entering that code and approving on the real Salesforce page. The attacker's device then receives the victim's token. Because the page is genuine, URL-based phishing filters do not help. Defenses: user training (never approve a code you did not start), scrutinizing the app name and scopes on the consent screen, limiting who can approve device flows, and monitoring for unexpected grants.

Q: Does the Device Flow return a refresh token? A: Yes, if you request the refresh_token (or offline_access) scope and the app allows it. This differs from JWT Bearer and Client Credentials, which return an access token only.

Q: What changed with Data Loader and the Device Flow? A: Salesforce removed device-flow support from the auto-installed Data Loader connected app on September 2, 2025, and recent Data Loader versions no longer support it. The Salesforce CLI's default connected app had a similar device-flow removal. Affected tools must move to another flow or use a dedicated connected app.

Talking point to explain it to anyone: "It is how you log in to Netflix on a new TV. The TV shows a short code, you type it on your phone, and the TV gets let in once you approve."

7. Key terms

device_code · user_code · verification_uri · interval · authorization_pending · slow_down · public client · polling — base definitions in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• OAuth 2.0 Device Flow for IoT Integration — Salesforce Help
• Configure an OAuth 2.0 Device Flow for External Client Apps — Salesforce Help
• Support for OAuth 2.0 Device Flow Authentication Is Being Removed in Data Loader on September 2, 2025 — Release Notes
• Data Loader OAuth 2.0 Device Flow Removal — Salesforce Help
• OAuth 2.0 Device Authorization Grant (RFC 8628)

Next: 07-username-password-flow.md — the deprecated flow that passes raw credentials, and what to use instead.

07 - Username-Password Flow

⛔ DEPRECATED / RETIRING. This flow passes a user's raw username and password straight to the token endpoint. Salesforce is retiring it and recommends you never build new integrations on it. One-liner: The app POSTs the user's username + password (with security token) and gets back an access token. Use when: Almost never. Understand it only for legacy systems and interviews. For real work, use 05-client-credentials-flow.md (server-to-server) or 02-web-server-flow.md + PKCE (user login). Grant type: password · Status: ⛔ Deprecated. Blocked by default for orgs created Summer '23+; full retirement targeted for Winter '27. Not supported by External Client Apps. Tokens returned: Access token only. No refresh token.

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

Imagine giving a delivery driver your actual house key, your alarm code, and your name so they can let themselves in whenever they like. That is this flow. The app holds the user's real Salesforce password and replays it to get a token. There is no claim ticket, no consent screen, no MFA prompt, no back-and-forth. Just credentials in, token out.

That is exactly why it is being killed. A password sitting in a config file or environment variable is a single point of catastrophic failure, and it bypasses multi-factor authentication entirely. Modern Salesforce wants either a passwordless machine identity (Client Credentials) or a proper interactive login (Web Server + PKCE). Learn this flow so you can recognize it and migrate off it, not so you can build with it.

2. When to use it (and when not)

Migration cheat sheet (say this in an interview):

Status details to quote: Username-Password is blocked by default for orgs created in Summer '23 or later. Salesforce announced its retirement, targeted for Winter '27, after which connected-app integrations using this flow will break. It is not supported by External Client Apps at all — only legacy Connected Apps. This is the single most important "what's changing" fact in Module 03.

3. How it works (sequence diagram)

Walkthrough

1. The app already has the user's password stored somewhere. That storage is the core risk.
2. The app POSTs to the token endpoint with grant_type=password, the username, the password (with the user's security token appended), plus the Connected App's client_id and client_secret. There is no browser, no consent screen, and no MFA.
3. Salesforce validates the credentials and returns an access token and instance_url. Critically, no refresh token is issued, so when the token expires the app must replay the password again.
4. The app calls the API with Authorization: Bearer <access_token>.

Notice the auth server is drawn in red. That is intentional: every step here is a security liability, and the absence of a consent/MFA step is exactly what regulators and Salesforce object to.

4. The actual requests & responses (legacy / for understanding only)

Do not build new code from this. It is shown so you can read existing integrations and migrate them.

The token request:

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -d grant_type=password \
  -d client_id=3MVG9...CONSUMER_KEY \
  -d client_secret=ABCD...CONSUMER_SECRET \
  -d username=integration.user@example.com \
  --data-urlencode "password=MyPasswordSECURITYTOKEN"

Key detail — the password field: for a user logging in from an untrusted network / IP, you must concatenate the password and the user's security token into one value: <password><securityToken> with no space. If the calling IP is in the org's trusted IP range (or the user has no security token), the token suffix may be omitted. Always send credentials in the POST body, never in the URL query string.

The token response:

{
  "access_token": "00D5g000004...!AQEAQ...",
  "instance_url": "https://MyDomainName.my.salesforce.com",
  "id": "https://login.salesforce.com/id/00D.../005...",
  "token_type": "Bearer",
  "issued_at": "1718700000000",
  "signature": "k0r...="
}

Note what is missing: there is no refresh_token and (unless you request openid) no id_token. When the access token expires the app has to send the password again, which is precisely why this pattern resists modern security controls.

Connected App setup (legacy):

1. The flow works only with a Connected App (External Client Apps do not support it).
2. Enable OAuth Settings and select scopes (e.g. api).
3. The org must have the username-password flow allowed (it is blocked by default for orgs created Summer '23+; an admin would have to explicitly permit it where still possible).
4. Copy the Consumer Key and Consumer Secret.
5. The integration user needs a security token (or the caller's IP must be trusted) and an MFA posture that this flow unfortunately bypasses.

5. Security pitfalls & gotchas

6. Interview Q&A

Q: What is the Username-Password flow and why is it dangerous? A: The app sends the user's raw username and password (security token appended) with grant_type=password to the token endpoint and gets an access token. It is dangerous because it stores and transmits the actual password, bypasses MFA, returns no refresh token, and offers no consent screen. Salesforce is retiring it.

Q: What is the retirement timeline? A: It is blocked by default for orgs created in Summer '23 or later, and Salesforce has announced full retirement targeted for Winter '27, after which connected-app integrations using it will stop working. It is also not supported by External Client Apps.

Q: An old integration uses this flow. How do you migrate it? A: Depends on context. For a backend/service job, move to Client Credentials (run-as user + secret, passwordless). For a certificate-based integration, JWT Bearer. For interactive user login, Web Server flow + PKCE. The goal is to eliminate the stored password.

Q: Why does this flow not return a refresh token? A: There is no user session or consent to keep alive in the OAuth sense. The design assumption was that the app can just replay the password to get a new access token, which is itself the security problem.

Q: Where do you append the security token, and when is it needed? A: You concatenate it to the end of the password (passwordSECURITYTOKEN, no space). It is required when the request comes from an untrusted IP. If the caller's IP is trusted by the org, it can be omitted.

Talking point to explain it to anyone: "It is like giving a contractor your actual house key instead of a temporary guest code. If they lose it, your whole house is exposed, and there is no way to tell who used it. We are replacing it with guest codes that expire and can be revoked."

7. Key terms

grant_type=password · security token · refresh token (absent here) · MFA bypass · confidential client — base definitions in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• OAuth 2.0 Username-Password Flow for Special Scenarios — Salesforce Help
• Retirement of OAuth 2.0 Username-Password Flow for Connected Apps — Release Notes
• OAuth 2.0 Username-Password Flow Blocked by Default in New Orgs — Release Notes
• Migrate from OAuth Username-Password to Client Credentials — Salesforce Help
• Block Authorization Flows to Improve Security — Salesforce Help

Next: 08-refresh-token-flow.md — how apps silently get a fresh access token without bothering the user.

08 - Refresh Token Flow

One-liner: After a user flow already issued a refresh token, the app silently trades that long-lived token for a fresh access token — no user, no re-login. Use when: An access token from a prior Web Server or User-Agent flow has expired and you need a new one without prompting the user. Grant type: refresh_token · Status: ✅ Recommended (the standard way to keep a user session alive). Tokens returned: A new access token (the same refresh token is reused, unless rotation is on).

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

Think of a gym membership card. When you join, the front desk checks your ID once and gives you a day pass (access token) plus a membership card (refresh token). The day pass expires every evening. But you don't re-show your ID each morning — you just tap your membership card at the turnstile and get a new day pass. The card itself lasts months, until it's cancelled.

That's this flow. It is not how you first get in — a user already logged in through an interactive flow that handed back a refresh token. From then on, whenever the short-lived access token expires, your app quietly taps the refresh token against the token endpoint and receives a new access token. The user never sees a login screen again until the membership (refresh token) is revoked or expires.

2. When to use it (and when not)

Real-world examples: a customer portal keeping a user connected for weeks; a mobile app that refreshes its session at app launch; middleware that maintains a per-user Salesforce session across long-running jobs.

Interview framing: this is a continuation flow, not an initial-login flow. JWT Bearer and Client Credentials never issue a refresh token — they just re-run their flow. Only user flows that requested the refresh_token scope can use this.

3. How it works (sequence diagram)

Walkthrough

1-2. The app calls the API with its current access token and gets 401 INVALID_SESSION_ID because the token expired. 3. Instead of prompting the user, the app POSTs to the token endpoint with grant_type=refresh_token, the stored refresh_token, and its client_id + client_secret. 4. Salesforce validates the refresh token against the app's OAuth policies. 5. Salesforce returns a new access token (and instance_url). The same refresh token keeps working unless rotation is enabled. 6-7. The app retries the call with the new token and succeeds.

4. The actual requests & responses

The refresh request — credentials in the body:

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -d grant_type=refresh_token \
  -d refresh_token=5Aep861...l4Lo \
  -d client_id=3MVG9...CONSUMER_KEY \
  -d client_secret=ABCD...CONSUMER_SECRET

You may instead send client_id:client_secret as an HTTP Basic Authorization header rather than in the body. The client_secret is omitted only for public clients that registered without one.

The token response — note there is no new refresh_token in the default case (you reuse the one you have):

{
  "access_token": "00D5g000004...!AQEAQ...",
  "signature": "k0r...=",
  "scope": "api refresh_token openid",
  "instance_url": "https://MyDomainName.my.salesforce.com",
  "id": "https://login.salesforce.com/id/00D.../005...",
  "token_type": "Bearer",
  "issued_at": "1718700000000"
}

Refresh token expiration policy (set on the Connected App's OAuth policies — pick one):

Refresh Token Rotation (RTR): if you enable it on the app, each refresh also returns a brand-new refresh token and invalidates the old one. The response then includes a fresh refresh_token, and your app must store it for next time. This shrinks the window a stolen token is usable.

Revoking a token — the kill switch (logout / compromise):

curl https://MyDomainName.my.salesforce.com/services/oauth2/revoke \
  -d token=5Aep861...l4Lo

Revoking the refresh token also invalidates the access tokens derived from it.

Salesforce as the client (outbound): when Salesforce itself holds the refresh token (via a Named Credential / External Credential of type "OAuth 2.0 — Authorization Code"), the platform performs this refresh for you automatically. You don't code the POST. See 14-named-credentials-and-external-credentials.md.

5. Security pitfalls & gotchas

6. Interview Q&A

Q: What is the Refresh Token flow and how does it differ from the other flows? A: It renews an access token after a user flow already issued a refresh token. It is not an initial-login flow — you can't start a session with it. The app POSTs grant_type=refresh_token with the stored token and client credentials, and gets a new access token, with no user interaction.

Q: Where does the refresh token come from? A: From an earlier Web Server or User-Agent flow that requested the refresh_token (a.k.a. offline_access) scope. Machine flows (JWT Bearer, Client Credentials) never issue one.

Q: Does each refresh return a new refresh token? A: By default no — you reuse the same one. If Refresh Token Rotation is enabled on the Connected App, each refresh returns a new refresh token and invalidates the previous one.

Q: What are the refresh token expiration policies? A: Valid until revoked (default), immediately expire, expire after n, and expire if not used for n. They're set on the Connected App's OAuth policies and control how long silent refresh keeps working.

Q: A user changed their password — what happens to the refresh token? A: It can be invalidated. A failed refresh should make the app fall back to a fresh interactive login. Admins can also kill tokens via /revoke or by revoking OAuth access on the user/app.

Q: How do you securely store a refresh token? A: It's a long-lived bearer secret — encrypt it at rest, keep it server-side (never in browser storage), scope it minimally, set an expiration policy, prefer rotation, and revoke on logout.

Talking point to explain it to anyone: "It's a gym membership card. You showed ID once at signup; after that you just tap the card each day for a new pass. The card lasts until it's cancelled — so guard it like a key."

7. Key terms

refresh_token · bearer token · Refresh Token Rotation (RTR) · refresh token expiration policy · /revoke endpoint · INVALID_SESSION_ID · offline_access scope — all defined in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• OAuth 2.0 Refresh Token Flow for Renewed Sessions — Salesforce Help
• OAuth 2.0 Refresh Token Flow — Mobile SDK Development Guide
• Manage OAuth Access Policies for a Connected App — Salesforce Help
• OAuth Endpoints — Salesforce Help

Next: 09-saml-bearer-assertion-flow.md — authenticating with a signed SAML assertion instead of a JWT.

09 - SAML Bearer Assertion Flow

One-liner: Your app builds and digitally signs a single SAML 2.0 assertion, POSTs it to the token endpoint, and gets back an access token. No user, no password, no refresh token. Use when: Server-to-server integration where the org already trusts a SAML signing certificate (common org-to-org or legacy SAML shops). Grant type: urn:ietf:params:oauth:grant-type:saml2-bearer · Status: ⚠️ Works, but JWT Bearer is usually the better modern choice (simpler token, same idea). Tokens returned: Access token only. No refresh token. No client secret needed.

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

Imagine a notarized letter. Instead of showing up in person to prove who you are, you write a letter that says "I am acting for user jdoe," then have it stamped by a notary whose seal the other party already recognizes. You mail that one sealed letter and they let you in.

In this flow your app is the letter-writer, the private key is the notary stamp, and Salesforce already holds the matching public certificate (you uploaded it to the Connected App). Your app assembles a SAML assertion, signs it with the private key, and sends it once. Salesforce checks the seal against the stored certificate and, if it matches, hands back an access token. Nobody logs in interactively.

Mental model: This is the JWT Bearer flow (04-jwt-bearer-flow.md) with one swap — the signed credential is a SAML 2.0 XML assertion instead of a compact JWT. Same "sign a statement, trade it for a token" plot; different envelope.

2. When to use it (and when not)

Real-world examples: a legacy enterprise service bus that already mints signed SAML for every system; one Salesforce org calling another org's API as an integration user; an older partner integration standardized on SAML before JWT Bearer was common.

The one-line decision rule: Pick SAML Bearer only because SAML already exists in your landscape. If you are starting fresh, pick JWT Bearer.

3. How it works (sequence diagram)

Walkthrough

1-3. Your app constructs a SAML 2.0 assertion, signs the XML with the private key, and base64url-encodes it (then URL-encodes it for the POST body). 4. The app POSTs to /services/oauth2/token with grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer and the encoded assertion in the assertion parameter. No client_secret is sent. 5. Salesforce verifies the signature against the certificate you uploaded to the Connected App, then checks Issuer, Audience, Recipient, Subject, and validity window. 6. If valid (and the app was previously authorized), Salesforce returns an access token and instance_url. There is no refresh token — when it expires you simply sign a fresh assertion and repeat. 7-8. The app calls the API with Authorization: Bearer <access_token>.

4. The actual requests & responses

Token endpoint (always your My Domain):

POST https://MyDomainName.my.salesforce.com/services/oauth2/token
Content-Type: application/x-www-form-urlencoded

The assertion must satisfy these rules (Salesforce validates each):

Sample assertion structure (abbreviated — the signed <ds:Signature> block is omitted for brevity):

<saml:Assertion Version="2.0" IssueInstant="2026-06-18T19:25:14.654Z" ...>
  <saml:Issuer>3MVG9...CONSUMER_KEY</saml:Issuer>
  <ds:Signature>...RSA-SHA256 signature over the assertion...</ds:Signature>
  <saml:Subject>
    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
      integration.user@example.com
    </saml:NameID>
    <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
      <saml:SubjectConfirmationData NotOnOrAfter="2026-06-18T19:30:14.654Z"
        Recipient="https://login.salesforce.com/services/oauth2/token"/>
    </saml:SubjectConfirmation>
  </saml:Subject>
  <saml:Conditions NotBefore="2026-06-18T19:25:14.654Z" NotOnOrAfter="2026-06-18T19:30:14.654Z">
    <saml:AudienceRestriction>
      <saml:Audience>https://login.salesforce.com</saml:Audience>
    </saml:AudienceRestriction>
  </saml:Conditions>
  <saml:AuthnStatement AuthnInstant="2026-06-18T19:25:14.655Z">...</saml:AuthnStatement>
</saml:Assertion>

The token request (curl):

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer \
  --data-urlencode assertion=PHNhbWw6QXNzZXJ0aW9u... (base64url of the signed XML)

The token response:

{
  "access_token": "00D5g000004...!AQEAQ...",
  "scope": "api",
  "instance_url": "https://MyDomainName.my.salesforce.com",
  "id": "https://login.salesforce.com/id/00D.../005...",
  "token_type": "Bearer"
}

Note the absence: no refresh_token, no id_token by default. Certificate-based machine flows hand back an access token and nothing to keep a session alive — see the interview trap in 01-authentication-fundamentals.md.

Connected App certificate setup checklist

1. Generate a key pair and self-signed certificate (e.g. keytool -genkey -keyalg RSA -keysize 2048 ..., export the .crt).
2. Create a Connected App and enable OAuth Settings.
3. Check "Use digital signatures" and upload the certificate (.crt) — Salesforce stores the public key; your app keeps the private key.
4. Add at least one OAuth scope (e.g. api). At least one scope beyond the default is required.
5. Save and copy the Consumer Key — this becomes the assertion's Issuer.
6. Authorize the app for the run-as user (admin pre-authorization via permitted users, or a prior interactive consent).

5. Security pitfalls & gotchas

6. Interview Q&A

Q: What is the SAML Bearer Assertion flow in one sentence? A: A server-to-server OAuth flow where the app presents a single, previously-trusted, digitally signed SAML 2.0 assertion to the token endpoint and receives an access token — no interactive login and no refresh token.

Q: How is it different from JWT Bearer? A: Identical pattern — sign a statement, exchange it for a token — but the signed credential is a SAML 2.0 XML assertion instead of a JWT. JWT Bearer is lighter and easier to implement, so SAML Bearer is mainly chosen when existing SAML infrastructure is already in place. Both return an access token only.

Q: Where does Salesforce get the key to verify the signature? A: From the certificate uploaded to the Connected App under "Use digital signatures." Salesforce holds the public certificate; the app holds the matching private key and signs with it. The assertion's Issuer must equal the app's Consumer Key.

Q: Does this flow return a refresh token? A: No. It is a certificate-based machine flow with no user session, so there is nothing to refresh. When the access token expires, the app signs a brand-new assertion and requests another token.

Q: Is a client secret required? A: No. Authentication is proven by the signature on the assertion, not by a client secret. You also do not have to store a refresh token.

Q: When would you pick SAML Bearer over JWT Bearer? A: When the organization already runs SAML — an existing IdP or middleware that natively emits signed SAML assertions — so reusing that machinery is cheaper than introducing JWT. Greenfield, you would pick JWT Bearer.

Talking point to explain it to anyone: "It's a notarized letter. The app writes a statement, stamps it with a private seal Salesforce already recognizes, and trades that one sealed letter for a temporary key — no one logs in."

7. Key terms

urn:ietf:params:oauth:grant-type:saml2-bearer · Assertion · Bearer token · Consumer Key / Client ID · Connected App · base64url — all defined in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• OAuth 2.0 SAML Bearer Assertion Flow — Salesforce Help
• OAuth 2.0 SAML Bearer Assertion Flow for Previously Approved Apps — Salesforce Help
• Integrating Multiple Orgs using the OAuth 2.0 SAML Bearer Assertion Flow — Salesforce Developers Blog
• SAML 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants — RFC 7522
• SAML Bearer Flow — Cloud Sundial

Next: 10-saml-assertion-flow.md — the related flow where an SSO'd user's IdP-signed assertion is exchanged for API access.

10 - SAML Assertion Flow (Access the API After Web SSO)

One-liner: A user who already authenticated through your SAML SSO can exchange that IdP-signed SAML assertion for a Salesforce access token, so the same login that got them into the UI also unlocks the API. Use when: You have SAML SSO configured for the org and a partner app wants API access using the very assertion it already federates with. Grant: Federates the same way as web SSO, using the SSO browser profile (urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser) · Status: ⛔ Rarely used today — JWT or Web Server is almost always preferable. Tokens returned: Access token only. No refresh token. No connected app required.

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

You walk into an office building and badge in at the lobby turnstile (web SSO). Normally that badge-in only gets you through the front door. This flow says: take the exact same badge swipe you just used at the lobby and present it at the parking-garage gate (the API) to get in there too, without a second sign-in.

In Salesforce terms: a user logs in via your SAML Identity Provider, which issues a signed SAML response asserting who they are. Instead of only using that response for the web UI, the partner app reuses the same assertion against the OAuth token endpoint to obtain an access token for API calls. The trust comes from the org's existing SAML Single Sign-On settings, not from a Connected App certificate.

Mental model: This is "SSO, but for the API." The user already proved who they are to your IdP; this flow converts that proof into an API token.

2. When to use it (and when not)

Reality check: The strict requirements (a single SubjectConfirmationData whose Recipient must be a Salesforce login/token URL, the correct Audience = your org's SAML Entity ID, IdP signature) make this impractical for most cases. In practice, almost everyone reaches for JWT Bearer, SAML Bearer, or the Web Server flow instead. Treat this as a "know it exists and can explain it" flow.

3. How it works (sequence diagram)

Walkthrough

1-2. The user authenticates against your SAML IdP (the same IdP your org trusts for web SSO). The IdP returns a signed SAML response asserting the user's identity. 3-4. The partner app takes that response, base64url-encodes it, then URL-encodes it for the POST body. 5. The app POSTs it to /services/oauth2/token, federating the same way as web SSO (the SSO browser profile assertion type). 6. Salesforce validates the assertion against the org's SAML Single Sign-On settings — the IdP signature, the Recipient (must be a Salesforce login/token URL), and the Audience (your org's SAML Entity ID). 7. On success Salesforce returns an access token and instance_url. No refresh token. 8-9. The app calls the API with Authorization: Bearer <access_token>.

4. The actual requests & responses

Token endpoint (your My Domain):

POST https://MyDomainName.my.salesforce.com/services/oauth2/token
Content-Type: application/x-www-form-urlencoded

The assertion must satisfy your org's SSO rules (Salesforce validates against SAML SSO settings):

The token request (curl) — illustrative:

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -d grant_type=assertion \
  -d assertion_type=urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser \
  --data-urlencode assertion=PHNhbWxwOlJlc3BvbnNl... (base64 of the IdP-signed SAML response)

Encoding nuance: the assertion is Base-64 encoded, then URL-encoded — the same value normally used for web single sign-on. Because it is the SSO assertion itself, you don't have to hand-craft a new one for the API.

The token response:

{
  "access_token": "00D5g000004...!AQEAQ...",
  "scope": "id api",
  "instance_url": "https://MyDomainName.my.salesforce.com",
  "id": "https://login.salesforce.com/id/00D.../005...",
  "token_type": "Bearer"
}

Setup checklist (org SSO, not a Connected App)

1. Configure SAML Single Sign-On in Setup: register your Identity Provider, its certificate, Issuer, and Entity ID.
2. Note the org's Login URL and OAuth 2.0 Token Endpoint from the SSO settings page — these are the valid Recipient values.
3. Ensure the IdP issues the SAML response with the correct Recipient and Audience for that org.
4. The partner app captures the IdP-signed assertion at login and reuses it against the token endpoint.

Why this is finicky: Salesforce supports only a single SubjectConfirmationData, and its Recipient must be a Salesforce login URL. An assertion built for a different service provider usually won't satisfy this, which is a big reason teams skip this flow in favor of JWT/SAML Bearer or Web Server.

5. Security pitfalls & gotchas

6. Interview Q&A

Q: What is the SAML Assertion flow for? A: It lets a user who authenticated through SAML SSO exchange that IdP-signed SAML assertion for a Salesforce access token, so an already-SSO'd user can reach the API — "federate with the API the same way you federate for web SSO."

Q: How does it differ from the SAML Bearer Assertion flow? A: Who signs and where trust lives. In SAML Assertion, the Identity Provider signs and Salesforce trusts it via the org's SAML SSO configuration — no Connected App. In SAML Bearer, the app itself signs with a private key whose certificate is uploaded to a Connected App. Bearer is for a server with no user present; Assertion is tied to a user who just did SSO.

Q: Does it need a Connected App? A: No. Trust is established through the org's SAML Single Sign-On settings. SSO must be enabled, and the assertion's Recipient and Audience must match the org. (SAML Bearer, by contrast, requires a Connected App with an uploaded certificate.)

Q: Why is it considered legacy / rarely used? A: The constraints are strict — a single SubjectConfirmationData whose Recipient must be a Salesforce login URL, the right Audience/Entity ID, and an IdP-signed response. For most server integrations JWT Bearer, SAML Bearer, or Web Server flow are simpler and more flexible, so this one is seldom chosen today.

Q: Does it return a refresh token? A: No. Like the certificate-based bearer flows, it returns an access token only. For long-lived user access you'd use the Web Server flow with refresh_token scope.

Talking point to explain it to anyone: "It's reusing your lobby badge-swipe at the parking gate. You proved who you are once at SSO login, and this flow turns that same proof into an API key — no second sign-in."

7. Key terms

Assertion · Identity Provider (IdP) · SAML SSO · Entity ID · Bearer token · urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser — all defined in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• SAML Assertion Flow for Accessing the API — Salesforce Help
• Configure SSO with Salesforce as a SAML Service Provider — Salesforce Help
• SAML Assertion Flow — Cloud Sundial
• Salesforce Single Sign-On Flows — Cloud Sundial

Next: 11-asset-token-flow.md — the token-exchange flow that issues scoped asset tokens for connected devices.

11 - Asset Token Flow

One-liner: A connected device exchanges a Salesforce access token plus its own signed actor token for an asset token (a JWT) that ties the physical device to a Salesforce identity and Asset record. Use when: You build IoT / connected-device integrations and need each device to authenticate to Salesforce as a verifiable "asset." Grant type: urn:ietf:params:oauth:grant-type:token-exchange · Status: ⚠️ Specialized (niche, valid only for connected-device / Service Cloud for IoT scenarios). Tokens returned: A signed asset token (JWT). No refresh token.

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

Imagine a fleet of vending machines. Each machine needs to prove "I am machine #4471, and I belong to this company's account" every time it phones home. You do not want to bake a human's password into the machine. Instead the machine carries its own tamper-proof badge.

The Asset Token Flow is OAuth 2.0 Token Exchange specialized for devices. The device (or a backend acting for it) first gets a normal access token, then trades that access token plus a JWT it signed itself for an asset token. The asset token is a JWT that says "this specific device is verified and linked to this Salesforce identity." Salesforce can also auto-create or link a Service Cloud Asset record during the exchange, so your CRM knows exactly which physical unit is talking.

The clever part: the device proves it holds a private key (the cnf claim carries its public key), so the asset token is bound to that one device. A stolen asset token is hard to reuse without the device's key.

2. When to use it (and when not)

Real-world examples: a smart thermostat that registers itself against a customer's Asset and streams telemetry; connected medical or industrial equipment that must be individually identifiable in Service Cloud; a fleet-management gateway that mints a per-device token before pushing events.

Honesty check: This is a specialized, low-frequency flow. Most integrations never touch it. Know what it is and when it applies. Do not reach for it unless "device = asset" is genuinely part of the design.

3. How it works (sequence diagram)

Walkthrough

1-2. The device (or a backend on its behalf) first obtains a standard access token using any supported OAuth flow. JWT Bearer is the natural partner for an unattended device. 3. The device signs its own JWT (the actor token) using a private key it holds. The matching public key travels in the token's cnf ("confirmation") claim. 4. The device POSTs to the token endpoint with grant_type=urn:ietf:params:oauth:grant-type:token-exchange, passing the access token as the subject token and the device JWT as the actor token. 5. Salesforce validates both tokens, reads the public key from cnf, and reads any asset claims (e.g. a serial number). 6. Salesforce links or registers an Asset record and publishes an AssetTokenEvent platform event so you can automate follow-up. 7. Salesforce returns the asset token: a signed JWT, bound to the device's key, that the device presents on subsequent calls.

4. The actual requests & responses

The token-exchange request (asset token issuance):

curl https://MyDomainName.my.salesforce.com/services/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "subject_token=00D5g000004...!AQEAQ..." \
  --data-urlencode "actor_token_type=urn:ietf:params:oauth:token-type:jwt" \
  --data-urlencode "actor_token=eyJraWQiOiI...DEVICE_SIGNED_JWT"

The device-signed actor JWT carries the device's identity and key. Conceptually its payload includes an asset claim (with a serial number to link an Asset) and a cnf claim (the device's public key):

{
  "iss": "device-issuer",
  "sub": "device-4471",
  "asset": { "serialNumber": "VM-4471-AC" },
  "cnf": { "jwk": { "kty": "RSA", "n": "0vx7...", "e": "AQAB" } }
}

The response — an asset token (JWT):

{
  "access_token": "eyJraWQiOiI...ASSET_TOKEN_JWT",
  "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "token_type": "Bearer",
  "expires_in": 3600
}

The returned access_token here is the asset token: a signed JWT whose cnf claim echoes the device's public key, binding the token to that device.

Validating an asset token (any downstream service can do this offline):

1. Split the JWT into header.payload.signature and base64url-decode the header.
2. Read the kid from the header and fetch the public signing key from the key endpoint: your site's My Domain URL with /id/keys appended.
3. Verify the JWS signature per RFC 7515, and validate the device binding using the public key in the cnf claim.
4. Use a standard JWT library (RFC 7519). Do not hand-roll signature checks.

Connected App setup checklist (asset token settings)

1. Create a Connected App (or External Client App) and enable OAuth Settings.
2. Select Enable Asset Tokens in the app's OAuth settings.
3. Asset tokens require the api and openid scopes. Add both.
4. Configure the asset token signing certificate (the cert Salesforce uses to sign the issued asset token) and the audiences the token is valid for.
5. Subscribe to AssetTokenEvent (a platform event) if you want Apex / Flow to react when a device registers. The event also stores the device's public key.

Where to dig deeper: Salesforce documents this under "OAuth 2.0 Asset Token Flow for Securing Connected Devices" and "Using and Validating Asset Tokens." It is part of the broader Token Exchange family. See Sources.

5. Security pitfalls & gotchas

6. Interview Q&A

Q: What problem does the Asset Token Flow solve? A: It securely ties a physical device to a Salesforce identity. The device gets a JWT (asset token) bound to its own key, and Salesforce can link or register a Service Cloud Asset record in the same exchange so the device is identifiable in CRM.

Q: What grant type does it use, and how is it structured? A: urn:ietf:params:oauth:grant-type:token-exchange. You pass a subject token (a normal access token) and an actor token (a JWT the device signed). Salesforce returns an asset token.

Q: Why an actor token and a subject token? A: The subject token establishes the Salesforce authorization context; the actor token proves the device's identity and carries its public key in the cnf claim. The asset token is bound to that key, so possession alone is not enough to impersonate the device.

Q: How does a downstream service trust an asset token without calling Salesforce on every request? A: It validates the JWT offline using standard RFC 7515/7519 steps, fetching the signing key from the /id/keys endpoint by kid, and checks the cnf proof-of-possession.

Q: Is this a mainstream flow? A: No. It is specialized for IoT / Service Cloud for IoT. For ordinary server-to-server work you would use Client Credentials or JWT Bearer. Knowing it exists and when it applies is the point.

Talking point to explain it to anyone: "It's a tamper-proof badge for a machine. The device shows Salesforce a badge it signed itself, Salesforce stamps it and records which machine it is, and the machine carries that stamped badge from then on."

7. Key terms

token-exchange · subject_token / actor_token · cnf (proof-of-possession) · JWT · Asset record · AssetTokenEvent — token and JWT basics are defined in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• OAuth 2.0 Asset Token Flow for Securing Connected Devices — Salesforce Help
• Using and Validating Asset Tokens — Salesforce Help
• OAuth 2.0 Token Exchange Flow — Salesforce Help
• AssetTokenEvent — Platform Events Developer Guide
• Enable OAuth Settings for API Integration — Salesforce Help

Next: 12-authorization-code-and-credentials-flow.md — the headless identity flow for fully branded customer login.

12 - Authorization Code and Credentials Flow (Headless Identity)

One-liner: Your app shows its own login UI (no Salesforce-hosted page), collects the user's credentials, and exchanges them through an authorization-code request for tokens against an Experience Cloud site. Use when: You build a fully branded customer (B2C) login for an Experience Cloud digital experience and refuse to redirect users to a Salesforce login screen. Grant type: authorization_code (credentials submitted directly, headless) · Status: ✅ Recommended for modern headless customer identity. Tokens returned: Access token + refresh token (+ ID token if openid).

New here? Read 01-authentication-fundamentals.md first for tokens, scopes, and endpoints.

1. The idea in plain English

Think of a bank's mobile app. You type your username and password into the bank's screen, with the bank's logo, fonts, and flow. You never get bounced to a generic "log in here" page run by a third party. Behind the scenes the app still does the secure handshake, but the front door is 100% the brand's.

That is the Authorization Code and Credentials Flow. It is part of Salesforce Headless Identity. Normally the Web Server flow (02) redirects the user to a Salesforce-hosted login page. Here, your app owns the entire UI and submits the collected credentials directly. Salesforce still runs a real authorization-code exchange under the hood, so you get the security of the code-then-token pattern without the Salesforce-hosted page. It is the modern, fully branded way to do customer and partner identity on Experience Cloud.

This single flow is the foundation for a family of headless experiences: classic password login, passwordless (OTP) login, self-registration, and guest access.

2. When to use it (and when not)

Real-world examples: a retailer's branded customer portal where shoppers sign in on the retailer's own screens; a mobile app that registers new customers in-app and logs them in via OTP; a partner community front-end built in React that never shows a Salesforce URL.

Why "headless"? The Salesforce identity service runs with no UI of its own in this flow. Your app is the head. That is the whole selling point: total control of branding and UX.

3. How it works (sequence diagram)

Walkthrough

1. The user types credentials into your branded UI. Salesforce never renders a page.
2. The app generates a PKCE code_verifier / code_challenge pair (PKCE is required for public clients and strongly recommended generally).
3. The app POSTs to the authorize endpoint of the Experience Cloud site, submitting the credentials directly (in request headers or the POST body) instead of via an interactive page.
4. Salesforce authenticates the user headlessly and returns an authorization code.
5. The app exchanges the code at the token endpoint with grant_type=authorization_code plus the PKCE code_verifier.
6. Salesforce returns an access token, refresh token, and optionally an ID token. From here it behaves like any user-context session.

The two-step "code then token" structure is the same as the Web Server flow. The difference is who collects the credentials: your app does, headlessly, instead of a Salesforce-hosted page.

4. The actual requests & responses

These calls go to your Experience Cloud site host (https://customersite.my.site.com), not the bare org login host.

Step 1 — headless authorization-code request (credentials submitted directly):

curl https://customersite.my.site.com/services/oauth2/authorize \
  -H "Auth-Request-Type: Named-User" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "response_type=code_credentials" \
  --data-urlencode "client_id=3MVG9...CONSUMER_KEY" \
  --data-urlencode "redirect_uri=https://app.example.com/callback" \
  --data-urlencode "scope=api refresh_token openid" \
  --data-urlencode "username=customer@example.com" \
  --data-urlencode "password=THE_USER_PASSWORD" \
  --data-urlencode "code_challenge=Psd...PKCE_CHALLENGE"

Step 1 response — an authorization code:

{
  "code": "aPrx...AUTH_CODE"
}

Step 2 — exchange the code for tokens:

curl https://customersite.my.site.com/services/oauth2/token \
  -d grant_type=authorization_code \
  -d code=aPrx...AUTH_CODE \
  -d client_id=3MVG9...CONSUMER_KEY \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=THE_ORIGINAL_RANDOM_STRING

Step 2 response — tokens:

{
  "access_token": "00D5g000004...!AQEAQ...",
  "refresh_token": "5Aep861...l4Lo",
  "id_token": "eyJraWQiOiI...",
  "instance_url": "https://customersite.my.site.com",
  "token_type": "Bearer",
  "issued_at": "1718700000000",
  "scope": "api refresh_token openid"
}

Header and parameter names for credential submission vary by headless variation (login, passwordless, registration). Treat the names above as representative and confirm exact headers against the current Headless Identity Implementation Guide before coding. See Sources.

External Client App setup checklist

1. Create an External Client App (not a classic Connected App). Enable its OAuth settings and the OAuth plugin.
2. Org-level: set oAuthCdCrdtFlowEnable = true on the OauthOidcSettings metadata type (the "OAuth and OpenID Connect Settings" page in Setup). This enables the Authorization Code and Credentials Flow for the org.
3. On the app's OAuth config, set isCodeCredFlowEnabled = true. Optionally set isCodeCredPostOnly = true to force credentials into the POST body only.
4. Keep Require Proof Key for Code Exchange (PKCE) enabled (required for public clients; it covers the Code and Credentials flow and its headless variations).
5. Select scopes: api, refresh_token / offline_access, and openid as needed.
6. Configure the Experience Cloud site for Headless Identity (the login/registration handlers and settings that headless flows route through).

Related headless flows (same family, same External Client App):

5. Security pitfalls & gotchas

6. Interview Q&A

Q: What is the Authorization Code and Credentials Flow and why does it exist? A: It is part of Salesforce Headless Identity. It lets an app build its own login UI for Experience Cloud customers and submit credentials directly, while Salesforce still runs a real authorization-code exchange behind the scenes. It exists so brands get total UX control without a Salesforce-hosted login page.

Q: How is it different from the standard Web Server flow? A: Same code-then-token security, but the Web Server flow redirects the user to a Salesforce-hosted page. Here the app collects the credentials itself (headless) and posts them. The browser never leaves your branded experience.

Q: What do you have to configure to turn it on? A: An External Client App with the OAuth plugin enabled, the org-level flag oAuthCdCrdtFlowEnable = true on OauthOidcSettings, isCodeCredFlowEnabled on the app, and an Experience Cloud site set up for Headless Identity. PKCE should stay on.

Q: Does it return a refresh token? A: Yes. It is a user-context flow, so you get an access token, a refresh token (with the right scope), and an ID token if you request openid. That distinguishes it from server flows like Client Credentials.

Q: What other headless flows are in the same family? A: Headless Passwordless Login (OTP), Headless Registration (self sign-up), Headless Forgot Password, and Headless Identity for Guest Users. They all build on this flow and the same External Client App.

Q: When would you NOT use it? A: For internal employee SSO (use SAML/OIDC), for backend system integrations (use Client Credentials), or when you are happy with the Salesforce-hosted login page (use the Web Server flow).

Talking point to explain it to anyone: "It's the bank-app login. You type your password on the bank's own screen, never a generic third-party page, but the secure handshake still happens behind the curtain."

7. Key terms

authorization_code · code_credentials · PKCE (code_challenge / code_verifier) · External Client App · OauthOidcSettings / oAuthCdCrdtFlowEnable · Headless Identity · Experience Cloud — token, scope, and PKCE basics are in 01-authentication-fundamentals.md.

Sources (Verified June 2026)

• Authorization Code and Credentials Flow for Private Clients — Salesforce Help
• Authorization Code and Credentials Flow for Public Clients — Salesforce Help
• Headless Identity APIs: Configure an External Client App for the Authorization Code and Credentials Flow — Salesforce Help
• Enable the Authorization Code and Credentials Flow — Headless Identity Implementation Guide
• What Is Headless Identity? — Headless Identity Implementation Guide
• Headless Passwordless Login Flow for Public Clients — Salesforce Help

Next: 13-connected-apps-vs-external-client-apps.md — the container comparison that explains why headless identity needs an External Client App.

13 - Connected Apps vs External Client Apps (ECA)

One-liner: Both are the container that holds your OAuth identity (consumer key, scopes, callback URL). Connected Apps are the original (2013); External Client Apps are the modern, packaging-friendly replacement (GA 2024). Use when: You need to register any app that talks to Salesforce over OAuth or SSO — pick the right container before you build a flow. Status: New Connected App creation is disabled by default on new orgs starting Spring '26 (rollout began Winter '26). For new builds in 2026, use an External Client App.