login()

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

Syntax

LoginResult = sfdc.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 Force.comAPI 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.comAPI 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:

Set the session ID in the SOAP header so that the Force.com API can validate subsequent requests for this session.
Specify the server URL as the target for subsequent service requests. You must change to the server URL, the login server only supports login calls.

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

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.

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 by clicking Setup | Security Controls. The default is 120 minutes (two hours).

Authenticating Active Self-Service Users

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).

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

private boolean login() {
  LoginResult loginResult = null;
  SoapBindingStub sfdc = null;
  try {
    //    Create binding object 
    sfdc = (SoapBindingStub) new SforceServiceLocator().getSoap();
    //    login
    loginResult = sfdc.login("username", "password");
  } catch (Exception ex) {
    System.out.println("An unexpected error has occurred." + ex.getMessage());
    return false;
  }

  System.out.println("Login was successful.");

  //    Reset the SOAP endpoint to the returned server URL
  sfdc._setProperty(SoapBindingStub.ENDPOINT_ADDRESS_PROPERTY, loginResult.getServerUrl());

  //    Create a new session header object
  //    add the session ID returned from the login
  SessionHeader sh = new SessionHeader();
  sh.setSessionId(loginResult.getSessionId());
  //    Set the session header for subsequent call authentication
  sfdc.setHeader(new SforceServiceLocator().getServiceName().getNamespaceURI(),
                       "SessionHeader", sh);

  // get user info
  try {
    GetUserInfoResult userInfo = sfdc.getUserInfo();
  } catch (Exception ex) {
    System.out.println("An unexpected error has occurred." + ex.getMessage());
    return false;
  }

  return true;
}

Sample Code—C#

private void login() 
{ 
  // Create service object 
  binding = new SforceService(); 
  // Invoke the login call and save results in LoginResult 
  LoginResult lr = binding.login("username","password"); 
  if (!lr.passwordExpired) {
  // Reset the SOAP endpoint to the returned server URL 
  binding.Url = lr.serverUrl; 
  // Create a new session header object 
  // Add the session ID returned from the login 
  binding.SessionHeaderValue = new SessionHeader(); 
  binding.SessionHeaderValue.sessionId = lr.sessionId; 
  GetUserInfoResult userInfo = lr.userInfo; 
  } else {
  Console.Writeine("You password is expired.");
  }
}

Arguments

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

Response

LoginResult

Faults

LoginFault

UnexpectedErrorFault