Elvis 5 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 2 flavors:

1. Handle a log-in 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:

Cookies

The log-in request will set a number of session cookies which all need to be passed along with any subsequent requests made to the Elvis server to handle authentication of those requests. This is both for API calls and for URLs of thumbnails, previews and originals that are made.

In Web browser environments, the Web browser will typically handle this for you.

When API calls are made from other environments such as node.js, a Java http client, .NET, or PHP, make sure to turn on cookie handling in the HTTP(s) library that you are using. In the node.js request library for example, this is handled using the cookie 'jar' options: https://github.com/request/request.

The following table shows the cookies are currently being used by the Elvis server (depending on situation).

Note: Do not rely on these explicitly, as the names of the cookies might change at any time in the future. Simply pass all cookies received during login with subsequent requests.

Examples

Successful login

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
}

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
}

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"
    }

Document history

• 1 November 2018: Updated section 'Parameters' by adding clientId.