Authentication overview

Salesforce API authentication governs how external applications and services establish trusted connections to access and manipulate data within a Salesforce organization. The platform primarily relies on the OAuth 2.0 framework, which provides a secure and standardized method for delegated authorization. This approach allows users to grant third-party applications limited access to their Salesforce data without sharing their actual credentials. Each API request to Salesforce must include a valid access token, which is obtained through one of several OAuth 2.0 flows.

The choice of OAuth 2.0 flow depends on the application type (e.g., web server, mobile app, desktop app, or headless service) and the user experience requirements. Salesforce's authentication mechanisms are designed to integrate with its robust security model, which includes profiles, permission sets, and connected apps to control what data and functionality an authenticated application can access. Understanding these components is essential for implementing secure and compliant integrations with the Salesforce platform, as detailed in the Salesforce API reference documentation.

Supported authentication methods

Salesforce supports multiple OAuth 2.0 flows, each tailored for specific integration scenarios. Selecting the appropriate flow is crucial for balancing security, user experience, and application architecture. These methods ensure that applications can securely authenticate and authorize access to Salesforce resources.

Method When to Use Security Level
OAuth 2.0 Web Server Flow Server-side web applications that can securely store a consumer secret and handle redirects (e.g., web apps, backend services). High (client secret is protected on the server)
OAuth 2.0 User-Agent Flow Client-side applications running in a browser that cannot securely store a consumer secret (e.g., single-page applications, mobile apps with embedded browsers). Medium (token exposed in browser history/URL, but short-lived)
OAuth 2.0 JWT Bearer Flow Server-to-server integrations where no user interaction is required, and the client application has a pre-established trust relationship with Salesforce (e.g., automated processes, integrations between trusted systems). Requires a digital certificate. Very High (no user interaction, uses strong cryptography)
OAuth 2.0 Device Flow Applications running on devices with limited input capabilities or no web browser (e.g., smart TVs, IoT devices, command-line tools). Medium (user interaction on a separate device, requires verification code)
OAuth 2.0 Refresh Token Flow To obtain a new access token without re-prompting the user for authorization after the initial access token expires. Used in conjunction with other flows. High (refresh token must be securely stored)
OAuth 2.0 Username-Password Flow (Legacy) Deprecated for most uses. Only for highly trusted clients with direct access to user credentials, typically for migration or specific testing scenarios. Not recommended for new integrations. Low (requires direct handling of user credentials, less secure)

More detailed information on each flow, including implementation steps, can be found in the Salesforce OAuth 2.0 authorization and authentication flows documentation.

Getting your credentials

To authenticate with the Salesforce API, you need to set up a Connected App within your Salesforce organization. A Connected App is a framework that allows external applications to integrate with Salesforce using APIs and standard protocols like OAuth 2.0. The process typically involves these steps:

  1. Log in to Salesforce: Access your Salesforce organization with an administrator account.

  2. Navigate to App Manager: From Setup, use the Quick Find box to search for App Manager, then select it.

  3. Create New Connected App: Click the New Connected App button. You will be prompted to provide basic information about your application.

  4. Configure API (OAuth) Settings:

    • Check Enable OAuth Settings.
    • Provide a Callback URL. This is where Salesforce redirects the user after successful authorization. For web server flows, this must be a secure HTTPS URL.
    • Select the desired OAuth Scopes. Scopes define the level of access your application requests (e.g., api for general API access, refresh_token for obtaining refresh tokens).

  5. Save the Connected App: After saving, Salesforce generates a Consumer Key (also known as Client ID) and a Consumer Secret (Client Secret). These are your primary credentials for initiating OAuth flows. The Consumer Secret is confidential and should be treated like a password.

  6. Manage Access: Configure profiles, permission sets, and IP ranges to control who can use the Connected App and from where. This is crucial for security and compliance.

For JWT Bearer Flow, you will also need to generate a self-signed digital certificate and upload it to the Connected App configuration, as described in the Salesforce JWT Bearer Flow documentation.

Authenticated request example

After successfully completing an OAuth 2.0 flow, your application receives an access_token. This token must be included in the Authorization header of subsequent API requests to Salesforce. The token typically has a limited lifespan, and you may need to use a refresh_token to obtain new access tokens without user re-authentication.

Here's an example using curl to query the Salesforce REST API for account records, assuming you have a valid access_token:

export ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
export INSTANCE_URL="YOUR_SALESFORCE_INSTANCE_URL" # e.g., https://yourdomain.my.salesforce.com
export API_VERSION="v58.0"

curl -X GET \
  "$INSTANCE_URL/services/data/$API_VERSION/query/?q=SELECT+Id,Name+FROM+Account+LIMIT+5" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"

In this example:

  • ACCESS_TOKEN is the token obtained from the OAuth flow.
  • INSTANCE_URL is the base URL of your Salesforce instance, which is also returned during the OAuth process.
  • API_VERSION specifies the Salesforce API version to use.
  • The Authorization: Bearer $ACCESS_TOKEN header authenticates the request.

When using Salesforce SDKs (e.g., Java, Node.js, Python), the authentication process is often abstracted, allowing developers to configure credentials and let the SDK handle token management, as shown in the Salesforce REST API Quick Start.

Security best practices

Implementing strong security measures is paramount when integrating with the Salesforce API due to the sensitive nature of CRM data. Adhering to these best practices helps protect your Salesforce organization and its data:

  • Use OAuth 2.0 Web Server or JWT Bearer Flows: Prioritize these flows for their enhanced security. Avoid the Username-Password flow unless absolutely necessary for specific, highly controlled scenarios, and ensure it's never used for new public-facing applications. The OAuth 2.0 specification provides a framework for secure delegated authorization.

  • Protect Consumer Secret: Treat your Connected App's Consumer Secret (Client Secret) as highly confidential. Never embed it directly in client-side code, mobile apps, or public repositories. Store it securely in environment variables, a secrets manager, or a secure configuration service.

  • Secure Callback URLs: Ensure that all Callback URLs configured in your Connected App use HTTPS. Only specify URLs that you control and that are designed to handle authorization redirects securely. Avoid using generic or insecure URLs.

  • Least Privilege Principle: Grant your Connected App and the users accessing it only the minimum necessary OAuth scopes, profiles, and permission sets. Regularly review and audit these permissions. For example, if an application only needs to read account data, do not grant it permission to delete records.

  • Token Management:

    • Short-lived Access Tokens: Salesforce access tokens are typically short-lived. Implement refresh token mechanisms to obtain new access tokens without requiring users to re-authenticate frequently.
    • Secure Refresh Token Storage: If using refresh tokens, store them securely. They are long-lived and can be used to generate new access tokens. Encrypt them at rest and restrict access.
    • Token Revocation: Implement functionality to revoke access tokens and refresh tokens if a security incident occurs or if an application's access is no longer needed. Salesforce provides API endpoints for token revocation.

  • Encrypt Data in Transit and At Rest: Always use HTTPS for all API communications. Ensure any data stored locally by your application is encrypted, especially sensitive information.

  • Implement IP Restrictions: Configure IP ranges in your Connected App or user profiles to restrict API access only from trusted IP addresses, adding an extra layer of security.

  • Audit and Monitoring: Regularly monitor Salesforce login history, API usage logs, and Connected App activity for suspicious patterns. Salesforce provides various tools for auditing and monitoring API access.

  • Error Handling: Implement robust error handling for authentication failures to prevent information leakage and ensure your application gracefully handles expired or invalid tokens.

  • Regular Security Reviews: Periodically review your Connected App configurations, OAuth policies, and overall integration security posture to adapt to evolving threats and compliance requirements. Adhering to the HIPAA compliance standards and PCI DSS requirements can further enhance data protection for relevant industries.