Headless Identity APIs: Headless Passwordless Login Flow for Private 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 a header to authenticate your request.

Include these parameters in the request body.

Here’s an example request to Headless Passwordless Login API. In this example, authentication is required but reCAPTCHA isn’t. 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
Authorization: Bearer <access token>
{
 "verificationmethod": "email",
"username": "janice.edwards@example.com",
"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
Authorization: Bearer <access token>
{
 "verificationmethod": "email",
"login_hint": "<user identifier such as email address, phone number, order number>",
"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 in the Apex Reference Guide.

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.MyDomainName.my.site.com/services/apexrest/code/exchange&
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 server-side 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

Server-Side Callback Handler Extracts Code and Performs Code Exchange

The server-side callback handler extracts the authorization code and other parameters from the 302 redirect. It then initiates the code exchange by sending a headless POST request to the 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=**********&
client_secret=*********&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
grant_type=authorization_code&
code_verifier=*******

Salesforce Grants an Access Token

After validating the app’s credentials. Salesforce returns an access token to the server-side callback handler. 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.

Server-Side Callback Handler Processes the Token Response

To get the access token, the callback handler processes the response and then returns the access token and state to the browser, along with user data, tokens, and session data. As a best practice, we recommend that you configure your server to store the access token, create a session for the app, and return the session to the app, instead of returning the access token. As the developer, you’re in full control of creating the session, storing the access token, and managing the logged-in state, so your specific implementation is up to you.

Here’s an example of a successful response in the browser console log.

{
"success":true,
"state":"https://MyExperienceCloudSite.my.site.com/",
"errMsg":"null",
"access_token":"00*******"
}

App Creates the User’s Session

The app receives the access token response and creates the user’s session.

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.