Skip to content
SteveTechArcSteveTechArc Courses

Token Exchange

Module 4 of 5 in the chapter Acting as Someone: The Impersonation Flows, chapter 11 of Securing Salesforce: Identity and Access. Each module stands on its own.

The question this module answers: What if Priya is already signed in, just not at Salesforce, and an app needs her Salesforce data?

Signed in, somewhere else

Section titled “Signed in, somewhere else”

Modules 1 to 3 had nobody home. This one is different: Priya is right there. She’s signed in. Just not at Salesforce.

Say the Burger House has its own login, run by its own identity provider, the one it uses for everything: its menu, its payments, its loyalty points. Whichever pops up the login screen is the identity provider, and here it isn’t Salesforce. Priya signed in there, and the Burger House holds her token from it.

Now she asks for her drink, and her drink is at the festival, in Salesforce. Does the Burger House send her to Salesforce’s login page, like chapter 9? She’s already signed in once. Asking again would be annoying, and she may not even know she has a Salesforce user.

Salesforce’s own example is the same story with real things: a customer portal outside Salesforce, using a third-party identity provider, with payments, shipping and customer data in other services, and support cases in Salesforce. The customers log in to the portal and see their cases, “without ever directly logging in to Salesforce” (S5).

The swap

Section titled “The swap”

You’ve seen this move before. In single sign-on, the identity provider’s assertion wasn’t good enough to get data on its own: Salesforce exchanged it for a session. In the web server flow, the code was exchanged for a wristband. Token exchange is the same idea, said out loud: the Burger House takes the token it already has, from the other identity provider, and swaps it for a Salesforce one.

Token exchange Four lanes: Priya's browser, the Burger House, another identity provider, and Salesforce's token endpoint and API. Step 1: Priya has already signed in at the identity provider the Burger House uses, and has her token. Step 2: she asks the Burger House for her drink, with no Salesforce login; the Burger House has her token from the other identity provider. Step 3: the Burger House exchanges her token, sending the token and its type with its client ID and the handler's name, at Salesforce's token endpoint, which runs your token exchange handler. The handler validates the token, optionally asking the identity provider whether it's good and who she is, and finds or makes her Salesforce user; the check passes and Salesforce sends back its tokens. Step 4: the Burger House fetches her drink from the API as Priya, and serves the burger and drink. Footnote: Priya never sees a Salesforce login page; the handler, like a registration handler, decides who she is in Salesforce. {"author": "Steve Simpson", "blueprint": "1.0.0", "builder": "standard 1.58.0", "built": "2026-11-05", "id": "DGM-IAM-AS-05", "rights": "\u00a9 2026 Twinshark LLC. All rights reserved.", "template": "cells 0.5.0", "theme": "stevetecharc 1.4.0"} PRIYA'S BROWSER THE BURGER HOUSE ANOTHER IDENTITY PROVIDER SALESFORCE: TOKEN ENDPOINT AND API 1. Already signed in at the Burger House's identity provider The identity provider the one the Burger House uses 2. Asks for her drink no Salesforce login Has her token from the other identity provider 3. Exchanges her token with its client ID and the handler's name The token endpoint runs your token exchange handler The identity provider, again optional: is the token good? who is she? Your handler validates it, finds or makes her user 4. Fetches her drink as Priya The API what Priya may see signs in her token her request burger + drink, after 4 her token + its type Salesforce tokens is this token good? yes, and who she is the access token her data Priya never sees a Salesforce login page. The handler, like a registration handler, decides who she is in Salesforce. HOW TO READ IT Salesforce the check passes © 2026 Twinshark LLC · stevetecharc.com
Click to enlarge
  1. Priya is already signed in at the Burger House’s identity provider, and the Burger House holds her token.
  2. She asks for her drink. No Salesforce login page.
  3. The Burger House posts her token to Salesforce’s token endpoint, saying what kind of token it is and which handler should check it (S5, S6).
  4. Salesforce runs your token exchange handler. It checks the token, and can ask the identity provider whether the token is good and who she is. Then it maps her to a Salesforce user (S5).
  5. Salesforce returns its tokens: an access token, and, if asked for, “a refresh token or ID token” (S5).
  6. The Burger House fetches her drink as Priya.

The handler: chapter 10 again

Section titled “The handler: chapter 10 again”

Does step 4 sound familiar? It should. In chapter 10, the registration handler took what Google said about Priya and decided which Salesforce user she was. The token exchange handler does the same job, for a token instead of a login. It’s an Apex class you write. It validates the outside token, maps the person in it to a Salesforce user, and “If it can’t find an existing user, it sets up a new User object and returns it to Salesforce for automated insertion” (S5).

So everything from chapter 10, module 3, applies here too:

  • Validate the token properly, with the identity provider’s keys, or by asking it. The handler is where the trust decision is made.
  • Match carefully, on something you can trust, and refuse rather than guess.
  • Only create users you mean to, with the right profile and licence.

On the wire

Section titled “On the wire”

The request is one POST to /services/oauth2/token, on your My Domain login URL or Experience Cloud site URL (S6):

ParameterWhat it holds
grant_typeurn:ietf:params:oauth:grant-type:token-exchange; for hybrid mobile apps, urn:ietf:params:oauth:grant-type:hybrid-token-exchange
subject_tokenThe token from the other identity provider
subject_token_typeWhat kind it is: an access token, a refresh token, an ID token, a SAML assertion, or any JWT
client_idThe app’s consumer key
token_handlerWhich handler checks it; optional, but “strongly recommended”
scopeOptional; a subset of the app’s scopes

Notice what it accepts: almost any token the other side might have, from an opaque access token to a SAML assertion (S6). And the client secret? Only if the app has a private back end that can keep it. For mobile apps and single-page apps, Salesforce says “we don’t recommend sending a secret because it can get leaked through the browser” (S6). Chapter 9’s rule, again.

Where it fits

Section titled “Where it fits”

On the map (chapter 5, module 3), token exchange sits in the row “A person, through an app”, beside the web server flow. That’s because there’s a person: Priya signed in, just somewhere else. That’s also why it can return a refresh token and an ID token, where modules 1 to 3 never could.

It’s the right tool when a company already has a central identity provider in front of many apps and services, and Salesforce is one more service behind it (S5). Salesforce fits into the identity design you already have, instead of the other way round.

It’s available in Enterprise, Performance, Unlimited and Developer editions (S5).

How is it different from chapter 10’s auth provider? The auth provider brings Priya into Salesforce itself, through its login page: she clicks a button and lands in Salesforce. Token exchange gives an app a Salesforce token for her, and she never sees Salesforce at all.

What’s next

Section titled “What’s next”

Module 5: the asset token. Things, not people.

What an architect decides here

Section titled “What an architect decides here”
  • Whether Salesforce should fit behind an existing identity provider, or be signed in to directly.
  • What the handler trusts: how it validates the token, and how it maps the person.
  • Whether the handler may create users, and which ones.
  • Whether the app sends a secret: only with a private back end.

Explore

Section titled “Explore”

Follow Me

© 2023–2026 Twinshark LLC. All rights reserved. · Content Use

Privacy notice

SteveTechArc is independent and is not affiliated with, sponsored by, or endorsed by Salesforce, Inc. Salesforce and related marks are trademarks of Salesforce, Inc.

Educational content, shared as is. Not professional, legal or financial advice. Salesforce changes several times a year, so check current Salesforce documentation before you rely on any platform detail.