Security and the API | SOAP API Developer Guide

User Authentication

Client apps must log in using valid credentials. After validating, the server provides the client app with a:

sessionId that is set into the session header so that all subsequent calls to the Web service are authenticated
URL address (serverUrl) for the client app's web service requests

Salesforce supports only the Transport Layer Security (TLS) protocol and frontdoor.jsp. Ciphers must have a key length of at least 128 bits.

User Profile and Permission Sets Configuration

As an org’s Salesforce admin, you control which features and views are available to users by configuring profiles and permission sets and assigning users to them. To access the API to issue calls and receive the call results, a user must have the API Enabled permission. Client apps can query or update only those objects and fields to which they have access via the permissions of the logged-in user.

To create, edit, or delete a profile, from Setup, enter Profiles in the Quick Find box, then select Profiles. To create, edit, or delete a permission set, from Setup, enter Permission Sets in the Quick Find box, then select Permission Sets.

The web services WSDL files return all available objects and fields for an org.

Note

Security Token

When users log in to Salesforce via the user interface, the API, or a desktop client such as Salesforce for Outlook, Connect Offline, Connect for Office, or the Data Loader, Salesforce authorizes the login as follows.

Salesforce checks whether the user’s profile has login-hour restrictions. If the user’s profile specifies login-hour restrictions, login attempts outside the specified hours are denied.
If the user has the Multi-Factor Authentication for User Interface Logins permission, the Salesforce login process prompts the user for an identity verification method in addition to their username and password. If the user’s account isn’t already connected to a verification method, such as the Salesforce Authenticator mobile app, Salesforce prompts the user to register a method.
If the user has the Multi-Factor Authentication for API Logins permission and connected an authenticator app to the account, the user must enter a verification code (TOTP) generated by the authenticator app. If the user uses the standard security token, Salesforce returns an error.
Salesforce then checks whether the user’s profile defines IP address range restrictions. If so, logins from outside the IP address range are denied. If the Enforce login IP ranges on every request session setting is enabled, the IP address restrictions are enforced for each page request, including requests from client apps.
If profile-based IP address restrictions aren’t set, Salesforce checks whether the user is logging in from a device that was previously used to access Salesforce.
- If the user is logging in from a device and browser that Salesforce recognizes, the login is allowed.
- If the user is logging in from an IP address on your org’s trusted IP address list, the login is allowed.
- If the user isn’t logging in from a trusted IP address, device, or browser that Salesforce recognizes, the login is blocked.

Whenever a login is blocked or returns an API login fault, Salesforce verifies the user’s identity.

For access via the user interface, the user is prompted to verify using Salesforce Authenticator (version 2 or later) or enter a verification code.
Users aren’t asked for a verification code the first time they log in to Salesforce.
Note
For access via the API or client app, if the Multi-Factor Authentication on API Logins permission is set on the user profile, users enter a TOTP verification code generated by an authenticator app.
If the permission isn’t set, users must add their security token to the end of their password to log in. A security token is a generated key from Salesforce. For example, if a user’s password is mypassword and the security token is XXXXXXXXXX, the user enters mypasswordXXXXXXXXXX to log in. Some client apps have a separate field for the security token.

Users can get their security token by changing their password or resetting their security token via the Salesforce user interface. When a user changes a password or resets a security token, Salesforce sends a new security token to the email address on the user’s Salesforce record. The security token is valid until the user resets the security token, changes a password, or has a password reset.

Before you access Salesforce from a new IP address, we recommend that you get your security token from a trusted network using Reset My Security Token.
Note

For more information about tokens, see Reset Your Security Token in Salesforce Help.

When a user’s password is changed, the user’s security token is automatically reset. To log in after the reset, the user adds the generated security token to the end of the password. Or the user enters the new password after you add the user’s IP address to the org’s list of trusted IP addresses.

If you reset the password of a user with the API only user permission, the user doesn’t receive a security token reset email. If you want API only users to receive a security token reset email when you reset their password, take these steps.

Temporarily assign the user to a profile that doesn’t have the API only user permission. For more information on user profiles and permissions, see User Permissions and Access.
Ask the user to manually reset their security token.
Reassign the user to a profile with the API only user permission.

If single sign-on (SSO) is enabled, users who access the API or a desktop client can’t log in unless their IP address is included on your org’s list of trusted IP addresses or on their profile, if their profile has IP address restrictions set. The delegated authentication authority usually handles login lockout policies for users with the Uses Single Sign-On permission. However, if the security token is enabled, your login lockout settings determine how many times a user can try to log in with an invalid security token before getting locked out. For more information, see Setting Login Restrictions and Setting Password Policies in Salesforce Help.

Sharing

Sharing refers to the act of granting read or write access to a user or group so that they can view or edit a record owned by other users, if the default access levels don’t permit such access. All API calls respect the sharing model.

The following table describes the types of access levels.

API Value	Salesforce User Interface Label	API Picklist Label	Description
None	Private	Private	Only the record owner and Users above that role in the hierarchy can view and edit the record.
Read	Read Only	Read Only	All Users and Groups can view the record but not edit it. Only the owner and users above that role in the hierarchy can edit the record.
Edit	Read/Write	Read/Write	All Users and Groups can view and edit the record.
ReadEditTransfer	Read/Write/Transfer	Read/Write/Transfer	All Users and Groups can view, edit, delete, and transfer the record. (Only available for cases and leads as an org-wide default setting.)
All	Full Access	Owner	All Users and Groups can view, edit, transfer, delete, and share the record. (Only available for campaigns as an org-wide default setting.)
ControlledByParent	Controlled by Parent	Controlled By Parent	(Contacts only.) All Users and Groups can perform an action (such as view, edit, or delete) on the contact based on whether he or she can perform that same action on the record associated with it.

Not all access levels are available for every object. See the Fields table for each object to learn which access levels are available, as well as other sharing details specific to that object.

For more information about sharing in general, see Salesforce Help.

In the API, you can create and update objects such as AccountShare and OpportunityShare that define sharing entries for records.

Note

Implicit Restrictions for Objects and Fields

Certain objects can be created or deleted only in the Salesforce user interface. Other objects are read-only—client apps cannot create(), delete(), or update() such objects. Similarly, certain fields within some objects can be specified on create() but not on update(). Other fields are read-only—client apps cannot specify field values in create() or update() calls. For more information, see the respective object descriptions in Object Basics.

API Access in Salesforce AppExchange Packages

The API allows access to objects and calls based on the permissions of the user who logs into the API. To prevent security issues from arising when installed packages have components that access data via the API, Salesforce provides additional security:

When a developer creates an AppExchange package with components that access the API, the developer can restrict the API access for those components.
When an administrator installs an AppExchange package, the administrator can accept or reject the access. Rejecting the access cancels the installation.
After an administrator installs a package, the administrator can restrict the API access of components in the package that access the API.

Editing API access for a package is done in the Salesforce user interface. For more information, see Manage API and Dynamic Apex Access in Packages in Salesforce Help.

API access for a package affects the API requests originating from components within the package; it determines the objects that the API requests can access. If the API access for a package is not defined, then the objects that the API requests have access to are determined by the user's permissions.

The API access for a package never allows users to do more than the permissions granted to the user. API access in a package only reduces what the user's permissions allow.

Choosing Restricted for the API Access setting in a package affects the following:

API access in a package overrides the following user permissions:
- Author Apex
- Customize Application
- Edit HTML Templates
- Edit Read Only Fields
- Manage Billing
- Manage Call Centers
- Manage Categories
- Manage Custom Report Types
- Manage Dashboards
- Manage Letterheads
- Manage Package Licenses
- Manage Public Documents
- Manage Public List Views
- Manage Public Reports
- Manage Public Templates
- Manage Users
- Transfer Record
- Use Team Reassignment Wizards
- View Setup and Configuration
- Weekly Export Data
If Read, Create, Edit, and Delete access aren’t selected in the API access setting for objects, users don’t have access to those objects from the package components, even if the user has the Modify All Data and View All Data permissions.
A package with Restricted API access can’t create users.
Salesforce denies access to Web service and executeanonymous requests from an AppExchange package that has Restricted access.

The following considerations also apply to API access in packages:

To manage API access to packages, see “Manage API and Dynamic Apex Access in Packages” in Salesforce Help.

Outbound Port Restrictions

For security reasons, Salesforce restricts the outbound ports you can specify to one of the following:

80: This port only accepts HTTP connections.
443: This port only accepts HTTPS connections.
1024–65535 (inclusive): These ports accept HTTP or HTTPS connections.

The port restriction applies to any feature where a port is specified, for example outbound messages, AJAX proxy, or single-sign on.