Documentation Version
Winter '16 (API version 35.0)
  • Winter '16 (API version 35.0) 35.0
  • Summer '15 (API version 34.0) 34.0
  • Spring '15 (API version 33.0) 33.0
  • Winter '15 (API version 32.0) 32.0
  • Summer '14 (API version 31.0) 31.0
  • Spring '14 (API version 30.0) 30.0
  • Winter '14 (API version 29.0) 29.0
  • English

Security and the API

Client applications that access your organization's Salesforce data are subject to the same security protections that are used in the Salesforce user interface. Additional protection is available for organizations that install AppExchange managed packages if those packages contain components that access Salesforce via the API.

User Authentication

Client applications must log in using valid credentials for an organization. The server authenticates these credentials and, if valid, provides the client application with:

  • a sessionId that must be set into the session header so that all subsequent calls to the Web service are authenticated
  • a URL address (serverUrl) for the client application'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

An organization's Salesforce administrator controls the availability of various features and views 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 be granted the “API Enabled” permission. Client applications 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 in the Salesforce user interface. 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 organization.

Security Token

When users log in to Salesforce, either 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 confirms that the login is authorized as follows:
  1. Salesforce checks whether the user’s profile has login hour restrictions. If login hour restrictions are specified for the user’s profile, any login outside the specified hours is denied.
  2. If the user has the “Two-Factor Authentication for User Interface Logins” permission, Salesforce prompts the user for a time-based token (which the user may also be prompted to create if it hasn’t already been added to the account) upon logging in.
  3. If the user has the “Two-Factor Authentication for API Logins” permission and a time-based token has been added to the account, Salesforce returns an error if a time-based token is not used to access the service in place of the standard security token.
  4. Salesforce then checks whether the user’s profile has IP address restrictions. If IP address restrictions are defined for the user’s profile, any login from an undesignated IP address is denied, and any login from a specified IP address is allowed. 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 applications.
  5. If profile-based IP address restrictions are not set, Salesforce checks whether the user is logging in from an IP address they have not used to access Salesforce before:
    • If the user’s login is from a browser that includes a Salesforce cookie, the login is allowed. If the user previously used the browser to log in to Salesforce and has not cleared the browser cookies, the browser has the Salesforce cookie.
    • If the user’s login is from an IP address in your organization’s trusted IP address list, the login is allowed.
    • If the user’s login is not from a trusted IP address or a browser with a Salesforce cookie, the login is blocked.
Whenever a login is blocked or returns an API login fault, Salesforce must verify the user’s identity:
  • For access via the user interface, the user is prompted to enter a token (also called a verification code) to confirm the user’s identity.


    Users aren’t asked for a verification code the first time they log in to Salesforce.

  • For access via the API or a client, users must add their security token (or time-based token if Two-Factor Authentication on API Logins is set on the user profile and the users have added a time-based token to their account) to the end of their password to log in.

    A security token is an automatically generated key from Salesforce. For example, if a user’s password is mypassword, and the security token is XXXXXXXXXX, the user must enter mypasswordXXXXXXXXXX to log in. Or, some client applications have a separate field for the security token.

    Users can obtain their security token by changing their password or resetting their security token via the Salesforce user interface. When a user changes their password or resets their security token, Salesforce sends a new security token to the email address on the user’s Salesforce record. The security token is valid until a user resets their security token, changes their password, or has their 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.

For more information about tokens, see “Reset Your Security Token” in the Salesforce online help.

When a user's password is changed, the user's security token is automatically reset. The user will experience a blocked login until he or she adds the automatically-generated security token to the end of his or her password or enters the new password after the administrator adds their IP address to the organization's list of trusted IP addresses.

If Single Sign-On (SSO) is enabled for your organization, users who access the API or a desktop client cannot log in to Salesforce unless their IP address is included on your organization's list of trusted IP addresses or on their profile, if their profile has IP address restrictions set. Futhermore, 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 for your organization, then your organization's login lockout settings determine the number of times a user can attempt to log in with an invalid security token before being locked out of Salesforce. For more information, see “Setting Login Restrictions” and “Setting Password Policies” in the online help.


In the Salesforce user interface, 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 organization access levels do not otherwise 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 organization-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 organization-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 the Salesforce online help.



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

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 applications 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 applications cannot specify field values in create() or update() calls. For more information, see the respective object descriptions in Object Basics.

API Access in 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 the Salesforce online 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 are not selected in the API access setting for objects, users do not 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 new 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:
  • Workflow rules and Apex triggers fire regardless of API access in a package.
  • If a component is in more than one package in an organization, API access is unrestricted for that component in all packages in the organization regardless of the access setting.
  • If Salesforce introduces a new standard object after you select restricted access for a package, access to the new standard object is not granted by default. You must modify the restricted access setting to include the new standard object.
  • When you upgrade a package, changes to the API access are ignored even if the developer specified them. This ensures that the administrator installing the upgrade has full control. Installers should carefully examine the changes in package access in each upgrade during installation and note all acceptable changes. Then, because those changes are ignored, the administrator should manually apply any acceptable changes after installing an upgrade.
  • S-controls are served by Salesforce and rendered inline in Salesforce. Because of this tight integration, there are several means by which an s-control in an installed package could escalate its privileges to the user’s full privileges. In order to protect the security of organizations that install packages, s-controls have the following limitations:
    • For packages you are developing (that is, not installed from AppExchange), you can only add s-controls to packages with the default Unrestricted API access. Once a package has an s-control, you cannot enable Restricted API access.
    • For packages you have installed, you can enable access restrictions even if the package contains s-controls. However, access restrictions provide only limited protection for s-controls. Salesforce recommends that you understand the JavaScript in an s-control before relying on access restriction for s-control security.
    • If an installed package has Restricted API access, upgrades will be successful only if the upgraded version does not contain any s-controls. If s-controls are present in the upgraded version, you must change the currently installed package to Unrestricted API access.

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



XML-RPC requests that originate from restricted packages will be denied access.

Outbound Port Restrictions

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

  • 80: This port only accepts HTTP connections.
  • 443: This port only accepts HTTPS connections.
  • 1024–66535 (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.