login()

Logs in to the login server and starts a client session.

Syntax

LoginResult = connection.login(string username, string password);

Usage

Use the login() call to log in to the login server and start a client session. A client application must log in and obtain a sessionId and server URL before making any other API calls.

When a client application invokes the login() call, it passes in a username and password as user credentials. Upon invocation, the API authenticates the credentials and returns the sessionId for the session, the user ID associated with the logged-in username, and a URL that points to the Force.com API to use in all subsequent API calls.

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.

After logging in, a client application needs to perform these tasks:

Development tools differ in the way you specify session headers and server URLs. For more information, see the documentation for your particular development tool.

Note
Multiple client applications can log in using the same username argument. However, this increases your risk of getting errors due to query limits. A user can have up to 10 query cursors open at a time. If 10 QueryLocator cursors are open when a client application, logged in as the same user, attempts to open a new one, then the oldest of the 10 cursors is released. If the client application attempts to open the released query cursor, an error results.

There is a limit of 3600 calls to login() per user per hour. Exceeding this limit will result in a “Login Rate Exceeded” error.

Enterprise and Partner Endpoints

In version 11.1 of the API and earlier, client applications built with the partner WSDL can send requests to the enterprise endpoint and enterprise WSDL applications can send requests to the partner endpoint. Beginning with version 12.0, this is not supported.

Logging In When Using a Proxy

If you log into Salesforce, via a proxy, set the proxy host and port on the instance of the ConnectorConfig class that you use to log in. Optionally, you may need to set the username and password, if you must authenticate on the proxy.

ConnectorConfig config = new ConnectorConfig();
config.setUsername(userId);
config.setPassword(passwd);
config.setAuthEndpoint(authEndPoint);
config.setProxy(proxyHost, proxyPort);
// Set the username and password if your proxy must be authenticated
config.setProxyUsername(proxyUsername);
config.setProxyPassword(proxyPassword);
try {
   EnterpriseConnection connection = new EnterpriseConnection(config);
   // etc.
} catch (ConnectionException ce) {
  ce.printStackTrace();
}

Session Expiration

Client applications do not need to explicitly log out to end a session. Sessions expire automatically after a predetermined length of inactivity, which can be configured in Salesforce from Setup by clicking Security Controls. The default is 120 minutes (two hours). If you make an API call, the inactivity timer is reset to zero.

Authenticating Active Self-Service Users

Note
Starting with Spring ’12, the Self-Service portal isn’t available for new organizations. Existing organizations continue to have access to the Self-Service portal.

To authenticate active Self-Service users, use the LoginScopeHeader to specify the Organization ID against which Self-Service users are authenticated. A Self-Service user must exist and be active before being authenticated (see SelfServiceUser).

Authenticating Customer Service Portal and Customer Community Users in Salesforce Communities

To authenticate an active Customer Community or Customer Portal user, use the LoginScopeHeader to specify the Organization ID of the org with communities. Customer Community and Customer Portal users must exist, be active, and belong to communities in the organization before being authenticated.

Logging Out

Salesforce recommends that you always call logout() to end a session when it is no longer needed. This ends any child sessions as well as the session being logged out. Logging out instead of waiting for the configured session expiration provides the most protection.

Sample Code—Java

This sample logs a user in using the specified username, password, and authentication endpoint URL. The sample writes user and session information to the console after a successful login. Before running this sample, replace the values for user name, password, and authentication endpoint with valid values.

To learn how to generate and import the Web service WSDL that you need to make API calls, see Step 2: Generate or Obtain the Web Service WSDL in the Quick Start.

public boolean loginSample() {
   boolean success = false;
   String username = "username";
   String password = "password";
   String authEndPoint = "https://login.salesforce.com/services/Soap/c/24.0/";

   try {
      ConnectorConfig config = new ConnectorConfig();
      config.setUsername(username);
      config.setPassword(password);        

      System.out.println("AuthEndPoint: " + authEndPoint);
      config.setAuthEndpoint(authEndPoint);

      connection = new EnterpriseConnection(config);

      // Print user and session info
      GetUserInfoResult userInfo = connection.getUserInfo();
      System.out.println("UserID: " + userInfo.getUserId());
      System.out.println("User Full Name: " + userInfo.getUserFullName());
      System.out.println("User Email: " + userInfo.getUserEmail());
      System.out.println();
      System.out.println("SessionID: " + config.getSessionId());
      System.out.println("Auth End Point: " + config.getAuthEndpoint());
      System.out
            .println("Service End Point: " + config.getServiceEndpoint());
      System.out.println();

      success = true;
   } catch (ConnectionException ce) {
      ce.printStackTrace();
   }

   return success;
}

Sample Code—C#

This sample logs a user in using the specified username and password. The result of the login call contains the service endpoint URL, which is the virtual server instance that’s servicing your organization, and a unique session ID. The sample sets these returned values on the binding. It sets the binding URL to the returned service endpoint. It also sets the session ID on the session header that is used on all API calls. Next, the sample writes user and session information to the console after a successful login. Before running this sample, replace the values for user name and password with valid values.

To learn how to generate and import the Web service WSDL that you need to make API calls, see Step 2: Generate or Obtain the Web Service WSDL in the Quick Start.

public bool loginSample()
{
   Boolean success = false;
   string username = "username";
   string password = "password";

   // Create a service object 
   binding = new SforceService();
 
   LoginResult lr;
   try
   {
      Console.WriteLine("\nLogging in...\n");
      lr = binding.login(username, password);

      /** 
         * The login results contain the endpoint of the virtual server instance 
         * that is servicing your organization. Set the URL of the binding 
         * to this endpoint.
         */
      // Save old authentication end point URL String authEndPoint = binding.Url; // Set returned service endpoint URL binding.Url = lr.serverUrl; /** Get the session ID from the login result and set it for the * session header that will be used for all subsequent calls. */ binding.SessionHeaderValue = new SessionHeader(); binding.SessionHeaderValue.sessionId = lr.sessionId; // Print user and session info GetUserInfoResult userInfo = lr.userInfo; Console.WriteLine("UserID: " + userInfo.userId); Console.WriteLine("User Full Name: " + userInfo.userFullName); Console.WriteLine("User Email: " + userInfo.userEmail); Console.WriteLine(); Console.WriteLine("SessionID: " + lr.sessionId); Console.WriteLine("Auth End Point: " + authEndPoint); Console.WriteLine("Service End Point: " + lr.serverUrl); Console.WriteLine(); // Return true to indicate that we are logged in, pointed
      // at the right URL and have our security token in place. success = true; } catch (SoapException e) { Console.WriteLine("An unexpected error has occurred: " + e.Message + "\n" + e.StackTrace); } return success; }

Arguments

Name Type Description
username string Login username.
password string Login password associated with the specified username.

The login request size is limited to 10 KB or less.

Response

LoginResult

Faults

LoginFault

UnexpectedErrorFault

© Copyright 2000–2014 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.