REST API:login Resource

Performs a Login action via the REST API

Requirements

• User must have a valid account on the AgileApps Cloud platform.
• All subsequent REST API calls execute within the context of the User that is logged in. As with all UI actions, this means that any subsequent REST API calls (to access levels, data visibility, team membership, etc.), are governed by the Data Access Permissions granted to the User.

Logging In

Method

POST

URI

https://{yourDomain}/networking/rest/login

Request

<syntaxhighlight lang="xml" enclose="div">

<platform>

  <login>
      <userName>jim@acme.com</userName>
      <password>jimacme</password>
  </login>

</platform> </syntaxhighlight>

Response

Session identifier required for succeeding REST calls, along with user details such as first name, last name, and employee number.

<syntaxhighlight lang="xml" enclose="div">

<platform>

 <login>
    <userId>qwe123rty456</userId>
    <email>jim@acme.com</email>
    <userName>jim@acme.com</userName>
    <firstName>Jim</firstName>
    <isForceChangePassword>true</isForceChangePassword>
    <lastName>Acme</lastName>
    <organizationName>Acme Inc.</organizationName>
    <organizationId>473474</organizationId>
    <timeZone>12</timeZone>
    <primaryTeamId>1</primaryTeamId>
    <employeeNumber></employeeNumber>
    <sessionId>xyz789uio987</sessionId>
    <cookieString>...</cookieString>
    <startingAppId type="" 
       uri="https://{yourDomain}/networking/rest/application/446yyt677wwz"
       displayValue="">446yyt677wwz</startingAppId>
    <userLocale>en</userLocale>
    <userDateFormat>MM/dd/yyyy</userDateFormat>
 </login>

 <message>
    0
    <description>Success</description>
 </message>

</platform> </syntaxhighlight>

Important: According to the password policy, the expiry frequency is the number of days the password remains valid before the user will be prompted to change it; Default: 90 days, Range: 15, 30, 60, 90, 120 days, or Never. The Client Application must check for the Login Response and the flag <isForceChangePassword> information every time when the user logs in. If the password becomes invalid based on the expiry frequency range, the flag must be set to "true" and the Client Application must prompt the user to change the password. It should also send the Update Password Request to the AgileApps Platform.

See also: REST API:Error Codes

Fields

These fields are required when logging in:

Name	Type	Description
userName	String	User's login name
password	String	User's login password

Sample Login Client

This code from the BaseClient sample program uses the Apache wink RestClient to make a REST login request and get a sessionId. It uses the Apache Wink client to post the login request, and calls a utility method defined in the BaseUtil] class to extract the sessionId from the response.

<syntaxhighlight lang="java" enclose="div" style="overflow: auto">

package demo.rest;

//HTTP Classes import org.apache.wink.client.RestClient; import org.apache.wink.client.Resource; import org.apache.wink.client.ClientResponse; import org.apache.commons.httpclient.HttpStatus;

// Apache Utilities import org.apache.commons.lang.StringUtils;

// Java Utilities import java.util.List; import java.io.InputStream; import javax.ws.rs.core.MultivaluedMap;

/*

* A base client that handles login and logout and provides utility
* methods for programs that use REST APIs.
* 
* Note:
* This class uses the Apache wink RestClient, which makes it
* pretty easy to make requests and handle responses. 
*/

public class BaseClient {

 String sessionId;
 RestClient client;
 
 String baseUrl = "https://{yourDomain}";
 String username = "yourName";
 String password = "yourPassword";
 
 public String login()
 { 
   String url = baseUrl + "/networking/rest/login";
   String xml = "<platform>"
       + "<login>"
           + "<userName>"+username+"</userName>"
           + "<password>"+password+"</password>"
       + "</login>"
       + "</platform>";
   try
   {
     System.out.println("Logging in");
     this.client = new RestClient();
     Resource resource = client.resource(url);
     resource.contentType("application/xml");
     resource.accept("application/xml");
     ClientResponse response = resource.post(xml);

     // Combine cookie parameters from the response header,
     // making a cookie string for use in subsequent requests.
     MultivaluedMap<String,String> headers = response.getHeaders();  
     String cookieString = "";
     List<String> cookieParams = headers.get("Set-Cookie");
     cookieString = StringUtils.join(cookieParams, "; ");

     return cookieString;
   }
   catch (Exception e)
   {
     e.printStackTrace();
   }
   return null;
 }

 // ...Various utility methods...

 public static void main(String args[])
 {
   BaseClient client = new BaseClient();
   String cookie = client.login();
   System.out.println("Session Cookie is: " + cookie);
   client.logout();
 }

} </syntaxhighlight>

Logging In as Customer Support

Login to a client tenancy as the "Customer Support" user, with system admin privileges.

Method

POST

URI

https://{yourDomain}/networking/rest/login/customerSupport

Request

<syntaxhighlight lang="xml" enclose="div">

<platform>

  <login>
      <userName>Adrian@AceAdmin.com</userName>
      <password>AdrianAdmin</password>
      <client_tenant_id>464938724568972</client_tenant_id>
  </login>

</platform> </syntaxhighlight>

Response

Session identifier required for succeeding REST calls, along with user details such as first name, last name, and employee number.

Fields

These fields are required:

• userName - Tenant admin's login name
• password - Tenant admin's password
• client_tenant_id - ID of the tenant to log into

Doing a Proxy Login

Permissions permitting, login to a client tenancy as a user in that tenancy, in order to review and/or fix the environment in which the customer is having problems.

Method

POST

URI

https://{yourDomain}/networking/rest/login/proxyLogin

Request

<syntaxhighlight lang="xml" enclose="div">

<platform>

  <login>
      <userName>Adrian@AceAdmin.com</userName>
      <password>AdrianAdmin</password>
      <proxy_user_id>464938724568972</proxy_user_id>
  </login>

</platform> </syntaxhighlight>

Response

Session identifier required for succeeding REST calls, along with user details such as first name, last name, and employee number.

Fields

These fields are required:

• userName - Tenant admin's login name
• password - Tenant admin's password
• proxy_user_id - ID of the user the admin will "become", for the duration of session

Switching Back to Your Original Session

This resource restores your original session, after having logged in to another tenancy using proxyLogin, so you don't have to log out of the customer's tenancy and then log in all over again. (It can be used in a REST client, or simply pasted into your browser to restore your previous session.)

Method

GET

URI

https://{yourDomain}/networking/rest/login/proxyLogin/switchBack

Response

Session identifier required for succeeding REST calls, along with user details such as first name, last name, and employee number.