Headless Identity APIs: Authorization Code and Credentials Flow for Public Clients

A key component of this flow is the client-side JavaScript that sends the authorization request, performs the code exchange, and processes the access token. Here’s a JavaScript example that uses a connected app.

var clientId = "<Connected App Client ID>";
var baseURL = "<Experience Cloud Domain>";
var redirectURL = "<Experience Cloud Domain>/services/apexrest/code/extraction"
      
// Performs the code exchange
function doCodeExchange(authorizeResponse) {
   //Perform Code Exchange
   //Get Access Token
   var client = new XMLHttpRequest();
   client.open("POST", authorizeResponse.sfdc_community_url + "/services/oauth2/token", true);
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.send("code=" + authorizeResponse.code + "&grant_type=authorization_code&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           getUserInfo(response.access_token, response.sfdc_community_url)
       }
   }
}

// Gets User Info
function getUserInfo(accessToken, userInfoBaseURL) {
   var client = new XMLHttpRequest();
   client.open("GET", userInfoBaseURL + "/services/oauth2/userinfo", true);
   client.setRequestHeader("Content-Type", "application/json");
   client.setRequestHeader("Authorization", "Bearer " + accessToken);
   client.send();
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           response.access_token = accessToken;
           document.getElementById("json").textContent = JSON.stringify(response, undefined, 2);
           document.getElementById("results").style.display="block";
       }
   }
}

//Starts the Login Process
function startLogin() {
   var username = document.getElementById('user_name').value;
   var password = document.getElementById('password').value;
  
   var encodedUNP = btoa(username + ':' + password);
   var client = new XMLHttpRequest();
  
   client.open("POST", baseURL + "/services/oauth2/authorize", true);
   client.setRequestHeader("Auth-Request-Type", "Named-User");
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.setRequestHeader("Authorization", "Basic " + encodedUNP);
   client.send("response_type=code_credentials&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           doCodeExchange(response);
       }
   }
   return false;
}    

Another key component is the server-side callback handler that extracts the code from the 302 redirect and returns it to the app. In this example, the handler is an Apex class exposed as a public REST endpoint, and is Cross Origin Resource Sharing (CORS) enabled to offer cross-site scripting protection. To simplify development, use the OAuth 2.0 echo endpoint to get the authorization code.

@RestResource(urlMapping='/code/extraction')
global class CodeExtractorAPI {
  
   @HttpGet
   global static CodeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
           return new CodeResponse(req.params.get('code'), req.params.get('sfdc_community_url'), req.params.get('sfdc_community_id'), req.params.get('state'));
       } catch (Exception e) {
           res.statusCode = 500;
           return new CodeResponse('Could not parse auth code redirect URI');
       }
      
   }
  
   // Response Wrapper
   global class CodeResponse {
       String code;
       String sfdc_community_url;
       String sfdc_community_id;
       String state;
       Boolean success;
       String errMsg;
      
       public CodeResponse(String code, String sfdc_community_url, String sfdc_community_id, String state) {
           this.code = code;
           this.sfdc_community_url = sfdc_community_url;
           this.sfdc_community_id = sfdc_community_id;
           this.state = state;
           this.success = true;
       }
      
        public CodeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }
}

End User Opens Third-Party App and Logs In

Your user opens your third-party app intending to log in. In your app, your login form appears showing username and password fields and a login button. Salesforce doesn’t provide this login form. Its look and feel are up to you. Your user enters their username and password and clicks the login button.

Third-Party App Generates code_verifier and code_challenge Values (Optional)

If you’re using the Proof Key for Code Exchange (PKCE) extension, the app generates values used to verify the authorization code.

Your flow includes this step only if you’re using the Proof Key for Code Exchange (PKCE) extension. As a security best practice, we strongly recommend using the PKCE extension when you implement the Authorization Code and Credentials Flow, especially for single-page apps. For more information on PKCE, see the specificationRFC 7636: Proof Key for Code Exchange by OAuth Public Clients provided by the Internet Engineering Task Force (IETF).

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.

Third-Party App Headlessly Requests an Authorization Code

From the browser, your custom app—via JavaScript—sends a headless authorization code request to the Salesforce Headless Login API authorization endpoint. If you aren't using headless user discovery, use either the GET or POST method for this request. If you are using headless user discovery, only POST requests are supported.

function startLogin() {
   var username = document.getElementById('user_name').value;
   var password = document.getElementById('password').value;
   var encodedUNP = btoa(username + ':' + password);
   var client = new XMLHttpRequest();
   client.open("POST", baseURL + "/services/oauth2/authorize", true);
   client.setRequestHeader("Auth-Request-Type", "Named-User");
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.setRequestHeader("Authorization", "Basic " + encodedUNP);
   client.send("response_type=code_credentials&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           console.log("here");
           console.log(client.response);
           response = JSON.parse(client.response);
           if (response.success) {
               getUserInfo(response.access_token, baseURL);
           }
       }
   }
   return false;
}    

For both GET and POST requests, you must include the header Auth-Request-Type: Named-User.

GET /services/oauth2/authorize? HTTP 1.1
Host: MyDomainName.my.site.com
Auth-Request-Type: Named-User
Authorization: Basic <encoded username:password>

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

If you’re using a POST request, you can include the Base64-encoded user credentials in an authorization header, or you can put them in the request body.

If you're using headless user discovery, you don't send a username and password. Instead, you send an identifier in the login_hint parameter, optional custom data, and a password. Include the identifier, custom data, and password in the body of a POST request. Don't use a GET request.

Optionally, to connect this flow to the headless guest flow, you can include a Uvid-Hint header with a JWT-based access token containing a UVID value, which is a Version 4 universally unique identifier (UUID) that’s generated and managed entirely by your app. To get an access token with a UVID, you must enable your external client app or connected app to issue JWT-based access tokens and implement the headless guest flow on your app.

If you implement the guest user flow on your app, you can optionally use this header to pass in a JSON Web Token (JWT)-based access token containing a unique visitor ID (UVID) tied to a guest user’s identity. By passing the UVID into a named user flow, you can carry contextual information from a guest user session, like the user’s cookie preferences, into a named user session.

You can also include the plain UVID value in the request body.

Note If you have the Require user credentials in the POST body for Authorization Code and Credentials Flow setting enabled on your external client app or connected app, you can send the user credentials only in the request body. With this setting enabled, you can’t use the GET method for the authorization code request. You can use only the POST method.

For both GET and POST methods, include these required parameters in the body of the authorization request.

You can also include these optional parameters in the authorization request.

(Optional) Headless User Discovery Handler Finds the User

If you're using a headless user discovery handler, the handler takes the login_hint and customdata parameters 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 Validates Credentials and Returns a 302 Redirect to Server-Side Callback Handler

Salesforce Headless Login API receives the authorization request. It validates the user credentials and returns an HTTP 302 redirect to a preconfigured URL containing the authorization code. Salesforce then automatically sends the redirect response to the redirect URL, which points to the server-side callback handler at the /code/extraction endpoint in this example. During this process, the browser isn’t redirected—everything happens behind the scenes.

Server-Side Callback Handler Extracts Code and Returns It to App

@RestResource(urlMapping='/code/extraction')
global class CodeExtractorAPI {
  
   @HttpGet
   global static CodeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
           return new CodeResponse(req.params.get('code'), req.params.get('sfdc_community_url'), req.params.get('sfdc_community_id'), req.params.get('state'));
       } catch (Exception e) {
           res.statusCode = 500;
           return new CodeResponse('Could not parse auth code redirect URI');
       }
      
   }
The response wrapper sets the variables for the code response, including success and error indicators.
// Response Wrapper
   global class CodeResponse {
       String code;
       String sfdc_community_url;
       String sfdc_community_id;
       String state;
       Boolean success;
       String errMsg;
      
       public CodeResponse(String code, String sfdc_community_url, String sfdc_community_id, String state) {
           this.code = code;
           this.sfdc_community_url = sfdc_community_url;
           this.sfdc_community_id = sfdc_community_id;
           this.state = state;
           this.success = true;
       }
      
        public CodeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }

<?
header('Access-Control-Allow-Headers: *');
header('Access-Control-Allow-Origin: *');
header('Content-Type: application/json; charset=utf-8');
$out = [];
foreach ($_GET as $name => $value) {
   $out[$name] = $value;
}
echo json_encode($out);
?>

After extracting the code, the callback handler sends it back to the browser.

App Receives Code Response and Performs Code Exchange

{"success":true,"state":"https://MyExperienceCloudSite.my.site.com/","sfdc_community_url":"https://MyExperienceCloudSite.my.site.com/vforcesite","sfdc_community_id":"0DBxxxxxxxxxxxx","errMsg":null,"code":"aPrxC1*******"}

The browser headlessly requests to exchange the code for an access token. In the client-side JavaScript example, the doCodeExchange function sends the code in a POST request to the Experience Cloud token endpoint.

var clientId = "<Connected App Client ID>";
var baseURL = "<Experience Cloud Domain>";
var redirectURL = "<Experience Cloud Domain>/services/apexrest/code/extraction"
      
// Performs the code exchange
function doCodeExchange(authorizeResponse) {
   //Perform Code Exchange
   //Get Access Token
   var client = new XMLHttpRequest();
   client.open("POST", authorizeResponse.sfdc_community_url + "/services/oauth2/token", true);
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.send("code=" + authorizeResponse.code + "&grant_type=authorization_code&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           getUserInfo(response.access_token, response.sfdc_community_url)
       }
   }
} 

For the access token request, you can use only a POST request—GET requests aren’t supported. You must include a Content-Type header. Include these required parameters in the request body.

You can also include these optional parameters in the token request.

Salesforce Grants an Access Token

{
"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 required parameters.

The access token response can also include these parameters.

App Processes Token Response and Creates the User Session

The browser stores the information from the token response and creates the user session. At this point, the user is logged in, and the client-side JavaScript calls the Salesforce User Info endpoint to confirm that the login was successful, as shown in this excerpt.

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.

// Gets User Info
function getUserInfo(accessToken, userInfoBaseURL) {
   var client = new XMLHttpRequest();
   client.open("GET", userInfoBaseURL + "/services/oauth2/userinfo", true);
   client.setRequestHeader("Content-Type", "application/json");
   client.setRequestHeader("Authorization", "Bearer " + accessToken);
   client.send();
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           response.access_token = accessToken;
           document.getElementById("json").textContent = JSON.stringify(response, undefined, 2);
           document.getElementById("results").style.display="block";
       }
   }
}

End User Is Logged in and Performs an Action in the App

Your user is now 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 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.

End 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. From the end user’s perspective, the entire process from logging in to accessing their data happened without ever requiring them to leave the app.