AJAX Toolkit Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Connecting to the API

The first portion of any JavaScript code that uses the AJAX Toolkit must make the toolkit available to the JavaScript code. The syntax for this is different depending on whether you are embedding JavaScript in a Visualforce page, or a button or link.
  • For Visualforce pages or any source other than a custom onclick JavaScript button, specify a <script> tag that points to the toolkit file:
    1<apex:page>
2          <script src="../../soap/ajax/31.0/connection.js" type="text/javascript"></script>
3     ...
4</apex:page>
  • For a custom onclick JavaScript button, specify the login call to log into the API: 
    1<body>
2     {!requireScript("/soap/ajax/31.0/connection.js")}
3     sforce.connection.login("username", "password");
4     ...
    The AJAX Toolkit picks up the endpoint and manages the session ID. You do not need to set them.

The version of the AJAX Toolkit is in the URL.

After this script executes, the toolkit is loaded and a global object, sforce.connection, is created. This object contains all of the API calls and AJAX Toolkit methods, and manages the session ID. No other session management is needed.

Salesforce checks the IP address from which the client application is logging in, and blocks logins from unknown IP addresses. For a blocked login via the API, Salesforce returns a login fault. Then, the user must add their security token to the end of their password in order to log in. A security token is an automatically-generated key from Salesforce. For example, if a user's password is mypassword, and their security token is XXXXXXXXXX, then the user must enter mypasswordXXXXXXXXXX to log in. 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. When the security token is invalid, the user must repeat the login process to log in. To avoid this, the administrator can make sure the client's IP address is added to the organization's list of trusted IP addresses. For more information, see “Security Token” in the in the SOAP API Developer's Guide.

It is recommended that you obtain your security token via the Salesforce user interface from a trusted network prior to attempting to access Salesforce from a new location.

Tip

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.