Elvis 4 REST API - login

http://yourserver.com/services/login
    ?cred=<base64 credentials>
    &username=<username>
    &password=<password>
    &nextUrl=<URL for next page>
    &failUrl=<URL for fail page>
    &locale=<language_COUNTRY_variant>
    &timezoneOffset=<timecode>
    &clientType=api_...
    &returnProfile=true

What does it do?

Authenticates your browser session.

All other REST calls require an authenticated session, otherwise they will respond with a "401 Unauthorized" status.

The login service can be used in two flavors:

1. Handle an AJAX login request

Use this if you want maximum control on the client side over what happens. It returns a JSON response with details about the result of your authenticate request. This mechanism is also used by the auto login function of the Elvis JavaScript library.

2. Handle form based login

Forwards to a 'success' or 'failure' URL after the authentication attempt. Use this to build a simple login page, see the following sample at GitHub. You can also tell the JavaScript library to use your login page whenever authentication is required.

Parameters

Return value

When nextUrl and failUrl are set, the service will respond with a 302 redirect. This will change the URL of the browser and navigate to the 'next' URL.

When nextUrl and failUrl are not set, the service returns a JSON response with the following information:

Examples

AJAX login with success

The following shows the response of a successful authentication attempt.

http://demo.elvisdam.com/services/login    
    ?username=guest
    &password=guest

{
  "sessionId" : "d7nkuyltv5z81tilxftfcu6ob",
  "serverVersion" : "3.0.3.622",
  "loginSuccess" : true
}

AJAX login with profile

The following shows the response of a successful authentication attempt.

http://demo.elvisdam.com/services/login    
    ?username=demo
    &password=demo
    &returnProfile=true

{
  "sessionId" : "rkz4i6kajppg1cdsqff1xdui5",
  "serverVersion" : "3.0.3.622",
  "userProfile" : {
    "authorities" : [ "ROLE_USER", ... ],
    "username" : "demo",
    "fullName" : "Demo User",
    "userZone" : "/Users/demouser",
    "groups" : [ "department1" ],
    "email" : "user@example.com"
  },
  "loginSuccess" : true
}

AJAX login failure

The following shows the response of a failed authentication attempt.

http://demo.elvisdam.com/services/login    
    ?username=guest
    &password=wrongpassword

{
      "loginSuccess" : false,
      "loginFaultMessage" : "Invalid username or password"
    }