Loading
Prepare for Email to Become the Default Login ExperienceRead More
Salesforce Enforces New Security Requirements in Summer 2026Read More
Secure Your Salesforce Org
Configure Your API Client to Use Mutual Authentication

You are here:

  1. Salesforce Help
  2. Docs
  3. Secure Your Salesforce Org

Configure Your API Client to Use Mutual Authentication

To use mutual authentication when calling Salesforce services via API, configure your client app to present your client certificate and chain to Salesforce. For security reasons, the client certificate must be used only in your org.

Required Editions

Available in: both Salesforce Classic and Lightning Experience
Available in: Enterprise, Performance, Personal, Unlimited, Developer, and Database.com Editions
User Permissions Needed
To create, edit, and manage certificates: Customize Application

To enforce mutual authentication on port 8443 for standard SSL/TLS connections:

(Assign to users with the API Only User permission)

 Enforce SSL/TLS Mutual Authentication
To access Salesforce only through a Salesforce API: API Only User
Important
Important With Google Chrome Root Program Policy v1.7, your client and server certificates can't originate from the same Public Root CA in the Chrome Trusted Root List. With this change, you can no longer use certificates that include Extended Key Usage (EKU) extensions for both client and server authentication. To prevent disruptions, transition to separate certificate hierarchies. The Google Chrome policy changes take effect on June 15, 2026, but you can experience issues with certificate renewal for some Public CA vendors before that date.

For more information, see Upcoming Mandatory Changes to Public Key Infrastructure (PKI).

For mTLS to work, the client must send a certificate chain. A certificate chain is a hierarchical order of certificates where one certificate issues and signs another certificate lower in the hierarchy. Upload a certificate chain as a single PEM-encoded certificate authority-signed (CA-signed) certificate representing the concatenated chain of certificates. The uploaded certificate chain must include the intermediate certificates in this order.

  • Start with the client certificate, and then add its signing certificate.
  • If more than one intermediate certificate exists between the client certificate and the root, add each certificate as the one that signed the previous certificate.
  • The root certificate is optional, and generally isn’t included.
Important
Important The client certificate must include any intermediate certificates in the chain when contacting port 8443. The intermediate certificates must be sent by the client with every request. You can upload either the leaf certificate or the full certificate chain.
Note
Note If you delete a mutual authentication certificate associated with a user who has the Enforce SSL/TLS Mutual Authentication user permission, it takes up to 5 minutes for the user’s session ID to be invalidated and for the certificate to be cleared from the cache.

Before you start, Set Up a Mutual Authentication Certificate for API Login.

  1. After you upload your mutual authentication certificate, log in to the Salesforce service using port 8443 for your My Domain login URL. Include your credentials and your signed certificate information.
    Your configuration using cURL can look something like this example. Replace “MyDomainName.my.salesforce.com:8443” with the specific instance’s endpoint, replace “@login.txt” with your login Soap message credentials, and replace “fullcert.pem:xxxxxx” with your certificate information.
    curl -k https://MyDomainName.my.salesforce.com:8443/services/Soap/u/31.0 -H "Content-Type: text/xml; charset=UTF-8" -H "SOAPAction: login" -d @login.txt -v -E fullcert.pem:xxxxxx
    Important
    Important Use your My Domain login URL. Don't use login.salesforce.com.
  2. After a session ID is returned from your call, you can perform other actions, such as queries.
    In this result, @accountQuery.xml is the file name containing the query Soap message with the session ID from the login response.
    curl -k https://MyDomainName.my.salesforce.com:8443/services/Soap/u/31.0 -H "Content-Type: text/xml; charset=UTF-8" -H "SOAPAction: example" -d @accountQuery.xml -v -E fullcert.pem:xxxxxx

For steps to set up certificate-based UI login using mutual authentication, see Certificate-Based Authentication.

See Also

 
Loading
Salesforce Help | Article