Headless Identity APIs: Headless Registration Flow for Private Clients

User Opens Third-Party App and Clicks Register

Your user opens your app and clicks a registration link, or they click a link to access a resource that requires registration.

Your App Displays a Registration Form

In your app, you natively display a registration form to collect user data. You control everything about this form, including its look, feel, and the user information that you want to collect.

There are a few considerations about what information you want to gather from users. When your app submits user information to Headless Registration API, Salesforce checks for an email address, username, last name, and password. You can collect this information from users or autogenerate it, but it must be included in your POST request. When deciding what information to include, make sure to collect an email address or phone number so that the user can verify their identity.

User Enters Their Information

In your app, the user enters their information in your registration form.

Your App Headlessly Sends the User Information to Headless Registration API

From the browser, your app sends a POST request to the headless registration endpoint (/services/auth/headless/init/registration) on your Experience Cloud site using Asynchronous Java and XML (AJAX).

Include these headers in your registration request.

Include these parameters in the request body.

Here’s an example POST request. In this example, the Experience Cloud settings are configured to require both authentication and reCAPTCHA, so the request includes an access token and a reCAPTCHA token.

POST /services/auth/headless/init/registration? HTTP 1.1
Host: MyDomainName.my.site.com
Content-Type: application/json
Authorization: Bearer **************
{
 “userdata”: {
  “firstName”: “Janice”
   “lastName”: “Edwards”
   “email”: “janice.edwards@example.com”
   “username”: “jedwards@myapp.com”
    }
 “customdata”: {
   {”mobilePhone”=”<mobile phone number>”
   }
 “password”: “*******”
 “recaptcha”:”***********”
 “verificationmethod”: “email”
“emailtemplate”: “unfiled$public/SalesNewCustomerEmail”
}

Salesforce Receives the Information and Returns a Request Identifier

Salesforce receives the user information. Because Salesforce hasn’t verified the user’s identity, it queues this information to be processed later.

If the information in the POST request is valid, Salesforce returns a success message to the app. This message includes a registration request identifier, which is important later in the flow. Here’s an example success message.

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

Salesforce Sends a One-Time Password to the User

Immediately after Salesforce receives the user data and sends a success message to the app, it sends a one-time password (OTP) via email or SMS, depending on the user’s verification method.

Your App Natively Displays a Verification Form

When you receive the success message, you natively display an OTP verification form in your app. Again, the look and feel of the verification experience is entirely up to you.

User Enters OTP in Verification Form

Your user receives the OTP via email or SMS and enters it in your verification form.

Your App Initializes the Authorization Code and Credentials Flow

When the user proves their identity, the app immediately initializes the Authorization Code and Credentials Flow with a request to Headless Login API.

Include these headers in the authorization request

Include these parameters in the request body.

Here’s an example request to Headless Login API, including PKCE.

POST /services/oauth2/authorize? HTTP 1.1
Host: MyDomainName.my.site.com
Auth-Request-Type: user-registration
Auth-Verification-Type: email
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64-encoded request ID:OTP>

response_type=code_credentials&
client_id=******&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
code_challenge=Y29kZ*******

Salesforce Verifies the Request, Retrieves the User Data, and Creates the User

Salesforce receives the authorization request and verifies the request ID and OTP. Salesforce uses this information to retrieve the queued user data and call the headless registration handler configured in your Experience Cloud site. The Apex handler creates the user in Salesforce and links them to an account.

Salesforce Returns a 302 Redirect to a Preconfigured URL Containing the Code

Salesforce returns an HTTP 302 redirect to a preconfigured URL containing the authorization code. The 302 redirect is processed within the browser, and the response is delivered headlessly to the redirect URL, which is a preconfigured callback endpoint on your server. Here’s an example 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 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.

For the access token request, you can use only a POST request—GET requests aren’t supported. There are no required headers for this request, but you can include a Content-Type header.

Include these parameters in the request body.

Here’s an example token request.

POST /services/oauth2/token HTTP 1.1
Host: MyDomainName.my.site.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=aPrxC1*******&
client_id=******&
client_secret=******&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/apexrest/code/exchange&
code_verifier=Y29kZ*******

Salesforce Grants an Access Token

Salesforce validates the token request and returns an access token response 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.

Callback Handler Processes Token Response and Returns Parameters to App

The server-side callback handler gets the access token from the response. The server-side callback handler 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.

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

App Processes Token Response and Creates the User Session

The app receives the token response, processes it, and creates the user session.

User Is Registered and Performs an Action in the App

Your user is now registered and logged in. They perform an action in your app that requires access to Salesforce data. For example, they click a button to view their travel booking history, which is stored in Salesforce.

Note When you set up your connected app or external client 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 travel booking history.