Headless Login Without a Username

For example, you have a headless ecommerce app that uses Salesforce headless identity for authentication. When a user makes a purchase, you send them an email with their order number. If a user wants to check the status of their order, they can follow a link in the email to log in to your app with their username and password. But you know that most users have too many usernames and passwords to keep track of across all of the different apps that they use. You want to make it easier for users to access the information that they want right away, with minimal friction. You want to develop a process where users log in with their order number instead.

Or you have a feature in your headless app where users can manage cases and communicate with your support team. To notify users about changes to their cases, you send them emails or SMS messages. In these notifications, you include a case number. So that users can access their case information immediately, you want to give users a way to log in with their case number.

With headless user discovery, there are a few different ways to deliver experiences like these ones. Users can log in with the identifier, like an order or case number, and their password. They can also log in with an identifier and then get a one-time password that’s sent to their email address or phone number, which they then use to complete login. To deliver coherent identity experiences across your app, you can develop a similar flow for password reset.

Log in with Any Identifier and a Password

You can deliver this experience with two different flows: the Authorization Code and Credentials Flow and the OAuth 2.0 for First-Party Applications login flow.

Here’s a breakdown of an Authorization Code and Credentials Flow where users log in with their order number.

• In your headless app, a user enters their order number and password.
• Your app sends a headless POST request to the Salesforce /services/oauth2/authorize endpoint. Among other parameters, the request includes a login_hint parameter. This parameter stores the user’s order number. The request also includes a customdata parameter with more information to identify the user, including cookies from the last time the user logged in.
• On the Salesforce side, an Apex headless login discovery handler uses the information from the login_hint and customdata parameters to find the email address that’s associated with this information. The handler checks that the user’s email address is verified.
• If the handler finds a user and can verify the credentials, Salesforce returns an authorization code. From here, the flow proceeds like a typical Authorization Code and Credentials Flow, where the app exchanges the code for a token that grants access to protected Salesforce data.
• At the end of the flow, the user is logged in and can instantly access their order data. No usernames or unnecessary navigation required.

For the OAuth 2.0 for First-Party Applications login flow, the end user experience is similar.

• In your headless app, a user enters their order number and password.
• Your app mints a client attestation JWT.
• Your app sends a headless POST request to the Salesforce /services/oauth2/authorize endpoint. The request includes login_hint and customdata parameters.
• Salesforce validates the client attestation JWT.
• The Apex headless login discovery handler uses the information from the login_hint and customdata parameters to find the email address that’s associated with this information. The handler checks that the user’s email address is verified.
• If the handler finds a user and can verify the credentials, Salesforce returns an authorization code. From here, the flow proceeds with your app exchanging the code for an access token.
• At the end of the flow, the user is logged in and can instantly access their order data.

Log in with Any Identifier and a One-Time Password (OTP)

Maybe you want to make this experience even easier for users by saving them the trouble of remembering their password. You can deliver this experience with headless passwordless login. Use the Headless Passwordless Login Flow, which calls Headless Passwordless Login API. Or, use the OAuth 2.0 for First-Party Applications headless passwordless login flow.

Here’s how the flow works when you call Headless Passwordless Login API.

• In your headless app, a user enters their order number.
• Your app sends a headless POST request to the Salesforce services/auth/headless/init/passwordless/login endpoint. Among other parameters, the request includes login_hint and customdata parameters.
• On the Salesforce side, an Apex headless login discovery handler uses the information from the login_hint and customdata parameters to find the user who’s associated with this information. The handler checks that the user’s email address is verified.
• If the handler finds a user, Salesforce returns a success message to your app along with a request identifier.
• Salesforce sends a one-time password (OTP) to the user’s email address.
• In your app, the user enters the OTP.
• From here, the flow proceeds by kicking off the Authorization Code and Credentials Flow.
• At the end of the flow, the user is logged in and can access their order data.

Here’s a breakdown of the flow using the OAuth 2.0 for First-Party Applications draft standard.

• In your headless app, a user enters their order number.
• Your app sends a headless POST request to the Salesforce services/auth/headless/init/passwordless/login endpoint. Among other parameters, the request includes login_hint and customdata parameters.
• On the Salesforce side, an Apex headless login discovery handler uses the information from the login_hint and customdata parameters to find the user who’s associated with this information. The handler checks that the user’s email address is verified.
• If the handler finds a user, Salesforce returns a success message to your app along with a request identifier.
• Salesforce sends a one-time password (OTP) to the user’s email address.
• In your app, the user enters the OTP.
• From here, the flow proceeds by kicking off the Authorization Code and Credentials Flow.
• At the end of the flow, the user is logged in and can access their order data.

Reset a Forgotten Password with Any Identifier

When you give users the ability to log in without a username, deliver the same experience for password reset. With username-free password reset, you can ease user frustration by giving them one less thing to remember.

• In your headless app, a user clicks a forgot password button.
• Your app displays a form where the user enters their order number.
• Your app sends a headless POST request to the Salesforce /services/auth/headless/forgot_password endpoint. Among other parameters, the request includes login_hint and customdata parameters.
• On the Salesforce side, an Apex headless login discovery handler uses the information from the login_hint and customdata parameters to find the user who’s associated with this information. The handler checks that the user’s email address is verified.
• If the handler finds a user, Salesforce returns a success message to your app.
• Salesforce sends a one-time password (OTP) to the user’s email address.
• In your app, the user enters the OTP.
• From here, the flow proceeds like a typical headless forgot password flow. The user enters their new password and Salesforce checks it against the password policies in your org.
• At the end of the flow, the user has a new password and can now log in.

Configure Headless User Discovery

Headless user discovery relies on an Apex handler that implements the Auth.HeadlessUserDiscoveryHandler interface. To simplify setup, your implementation uses the same handler for all flows where you use headless user discovery.

First, develop your Apex handler to include custom logic to find the user based on the information in the login_hint and customdata parameters. For security, make sure that your handler checks whether the user’s email address or phone number is verified. For more information about developing your handler, see Auth.HeadlessUserDiscoveryHandler in the Apex Reference Guide.

Then, add your handler to your Experience Cloud settings. For headless passwordless login flows, headless user discovery is enabled when you add the handler. For the Authorization Code and Credentials Flow, OAuth 2.0 for First-Party Applications login flow, and the headless forgot password flows, enable an extra setting to use the handler that you add.

For flows that use Headless Identity APIs, see these steps.

• Configure Experience Cloud Settings for Headless Passwordless Login
• Configure Experience Cloud Settings for the Headless Forgot Password Flow

For flows that use the OAuth 2.0 for First-Party Applications standard, see OAuth 2.0 for First-Party Applications: Configure Experience Cloud Settings.

Finally, configure the headless flows. Each flow is different, but all flows include a request where you send the login_hint and customdata parameters. The customdata parameter is optional, but if you include it with one flow, use it with all flows because they all use the same handler.

For flows that use Headless Identity APIs, see these resources.

• Log in with identifier and password: Authorization Code and Credentials Flow for Public Clients or Authorization Code and Credentials Flow for Private Clients
• Log in with identifier and OTP: Headless Passwordless Login Flow for Public Clients or Headless Passwordless Login Flow for Private Clients
• Password reset: Headless Forgot Password Flow

For flows that use the OAuth 2.0 for First-Party Applications standard, see these resources.

• Log in with identifier and password: OAuth 2.0 for First-Party Applications: Headless Username-Password Flow for Private Clients
• Log in with identifier and OTP: OAuth 2.0 for First-Party Applications: Headless Passwordless Login for Private Clients