Headless Identity APIs: Headless Passwordless Login Flow for Public Clients

End User Enters Their Email Address or Phone Number for Login

The flow starts when an end user visits your app. Your app natively displays a login form requesting only the user’s email address or phone number. Or, if you're using a headless user discovery handler that looks up users based on a different identifier, such as an order number, your app can display a login form prompting the user for the identifier. The end user enters their information and clicks a button to log in.

Your App Finds the Username

If you're not using a headless user discovery handler, your app looks up the user’s email address or phone number and finds the associated username.

If you're using a headless user discovery handler, your app skips this step. Your handler looks up the user after you submit the initial request.

Your App Sends a Request to Headless Passwordless Login API

From the browser, your app sends a headless POST request to the headless passwordless login endpoint (services/auth/headless/init/passwordless/login) on your Experience Cloud site.

Include these parameters in the request body.

Here’s an example request to Headless Passwordless Login API. This request is for an implementation that doesn't use a headless user discovery handler.

POST /services/auth/headless/init/passwordless/login? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
{
 "verificationmethod": "email",
"username": "janice.edwards@example.com",
"recaptcha": "***********",
"emailtemplate": "unfiled$public/SalesNewCustomerEmail"
}

Here's an example request if you’re using a headless user discovery handler.

POST /services/auth/headless/init/passwordless/login? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
{
 "verificationmethod": "email",
"login_hint": "<user identifier such as email address, phone number, order number>",
"recaptcha": "***********",
"emailtemplate": "unfiled$public/SalesNewCustomerEmail"
}

(Optional) Headless User Discovery Handler Finds User

If you're using a headless user discovery handler, the handler takes the login_hint parameter and finds the associated user. The handler confirms that the email address or phone number for the user is verified.

For an example handler, see Auth.HeadlessUserDiscoveryHandler.

Salesforce Returns a Request Identifier to Your App

If the request is successful, Salesforce sends back a success message that includes an identifier for the request, which is important later in the flow when it’s exchange for an access token. Here’s an example success message.

{
    "status”: "success",
    "email": "jedwards@example.com",
    "identifier": “0RXXXXXXXX”
}

Salesforce Sends an OTP to the User

Immediately after Salesforce sends the request identifier to your app, it also sends the user an email or SMS text message with the OTP.

Your App Displays a Verification Form

In your app, you natively display a verification form where the user can enter their OTP.

End User Enters OTP

The end user receives the OTP via email or text message and enters it in the verification form in your app.

Your App Generates Parameters for PKCE

If you’re using the PKCE extension—which we strongly recommend— your app generates code_verifier and code_challenge parameters.

The PKCE specification defined in RFC 7636 also includes an optional code_challenge_method parameter that you can send in the authorization request. Salesforce ignores any value that you send in this parameter and defaults to SHA256.

Your App Sends a Request to the Authorization Endpoint

As soon as the user verifies their identity by entering the OTP, your app initializes the Authorization Code and Credentials Flow with a request to the authorization endpoint, where it exchanges the request ID and OTP for an authorization code.

Include these headers in the authorization request.

Include these parameters in the request body.

Here’s an example request to the authorization endpoint. This example includes PKCE.

POST /services/oauth2/authorize? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
Auth-Request-Type: passwordless-login
Auth-Verification-Type: email
Authorization: Basic <base64-encoded identifier:OTP

response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/oauth2/echo&
code_challenge=********

Salesforce Verifies the Request and Returns a 302 Redirect

When the request hits the authorization endpoint, Salesforce verifies the request identifier and OTP. Salesforce then returns an HTTP 302 redirect to a preconfigured URL containing the authorization code. If the flow is happening in the browser, the 302 redirect is processed in the browser and Salesforce automatically sends the redirect response to the redirect URL, which is the callback endpoint. Here’s an example preconfigured URL.

https://www.MyDomainName.my.site.com/services/apexrest/code/exchange?code=aPrxC1*******
&sfdc_community_url=https%3A%2F%2FMyDomainName.my.site.com&sfdc_community_id=0DBxxxxxxxxxxxx

Callback Endpoint Sends the Authorization Code to Your App

The callback endpoint extracts the authorization code and returns it to your app. In these code examples, the redirect URL points to the /services/oauth2/echo callback endpoint on the Experience Cloud site. This endpoint automatically parses the 302 redirect, extracts the authorization code and other parameters, and returns them to your app in JSON format.

App Initiates Token Exchange

Your app receives the code response. To get an access token, the app initiates the code exchange with a headless POST request to the /services/oauth2/token endpoint.

This request has no headers. Include these parameters in the request body.

Here’s an example token request. This example uses PKCE.

POST services/oauth2/token? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com

code=********&
client_id=**********&
redirect_uri=https://MyExperienceCloudSite.my.site.com/services/oauth2/echo&
grant_type=authorization_code&
code_verifier=*******

Salesforce Grants an Access Token

After validating the app’s credentials. Salesforce returns an access token to the browser. Here’s an example access token response in JSON format.

{
"access_token":"*******************",
"sfdc_community_url":"https://MyDomainName.my.site.com",
"sfdc_community_id":"0DBxxxxxxxxxxxx",
"signature":"ts6wm/svX3jXlCGR4uu+SbA04M6qhD1SAgVTEwZ59P4=",
"scope":"openid api",
"id_token":"XXXXXX",
"instance_url":"https://yourInstance.salesforce.com",
"id":"https://yourInstance.salesforce.com/id/00Dxxxxxxxxxxxx/005xxxxxxxxxxxx",
"token_type":"Bearer",
"issued_at":"1667600739962"
}

The access token response contains these parameters.

App Creates the User’s Session

The browser stores the information from the token response and creates the user session. Your app calls the Salesforce User Info endpoint to confirm that the login was successful.

Note Ensure that you complete a full security review of your access token storage. Never store the access token in the browser’s local storage, and avoid storing it in a cookie if possible.

The User Is Logged In and Performs an Action in the App

The end user is now logged in, and they perform an action in your app that requires access to Salesforce data. For example, they click a button to view their order history, which is stored in Salesforce.

Note When you set up your external client app or connected app for the Authorization Code and Credentials Flow, you set the Permitted Users policy to Admin-approved users are pre-authorized and configure which profiles or permission sets can access the app. With this policy, users access the app without authorizing it, so they don’t get an authorization screen prompting them to let the app access their data.

App Makes an Authenticated Call to a Salesforce Endpoint

To access the user’s Salesforce data, your app uses the access token to make an authenticated call to a protected Salesforce endpoint, such as a Salesforce API.

User Can Access Salesforce Data

The user can now access protected Salesforce data in your app. For example, they can see their order history. From the user’s perspective, the entire process from logging in to accessing their data happened without ever requiring them to leave the app.