WoodWing Help Center

Elvis 6 REST API - login

Elvis 6 REST API - login

POST

http://yourserver.com/services/login
    ?cred=<base64 credentials>
    &username=<username>
    &password=<password>
    &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 for handling 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.

Note: As an alternative method, use REST API login.

POST requests only

This REST API only accepts POST requests, not GET requests. It returns a CSRF token that can be used for future POST requests.

For more information including examples, see Elvis 6 REST API - Performing a POST request with a csrf token.

Parameters

cred

Base 64 encoded credentials.

cred=<base64Encode( username + ":" + password )>

Base64 encoding is not secure. Use https to make login secure.

Optional. Either cred or username and password must be specified.

username

The username to be used to login. This should match a valid username from the LDAP or ActiveDirectory server or from the internal Elvis users. Sometimes an LDAP configuration supports various usernames for one user.

Optional. Either cred or username and password must be specified.

password

The password for the user. Since this is passed to the server as plain text, use https to make login secure.

Optional. Either cred or username and password must be specified.

clientType

Custom client type that will be displayed in the usage history of the asset. Used to track which interface was used to perform the operation. The client type must be prefixed with "api_", for example: "api_MyPublicWebsite".

Optional. When not specified, operations will be tracked without a client type.

returnProfile

Specify 'true' to return profile with login response.

Optional. When not specified, profile details are not returned.

Return value

The service returns a JSON response with the following information:

loginSuccess

true | false

Indicates if login was successful.

serverVersion

The version of the server. This can be used to check if the Elvis Server you are connecting to meets your minimum server version requirements.

loginFaultMessage

A message indicating why login failed.

Only returned when loginSuccess is false.

userProfile

An object with details about the user.

Only returned when loginSuccess is true and the returnProfile parameter is set to true.

For details about the properties in the object, see REST profile.

csrfToken A cross-site request forgery (CSRF) token.

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.

AWSELB Only in AWS environments. The AWS load balancer cookie that ensures subsequent requests are sent to the same cluster node. This results in sticky sessions which provide best performance by optimizing cache usage in each of the nodes in the Elvis cluster.
authToken Primary Elvis authentication token cookie.

Examples

Successful login

The following shows the response of a successful authentication attempt.

login

http://demo.elvisdam.com/services/login    
    ?username=guest
    &password=guest
{
  "serverVersion" : "6.1.1.622",
  "loginSuccess" : true,
  "csrfToken" : "ababababababab"
}

Login with profile

The following shows the response of a successful authentication attempt.

login
http://demo.elvisdam.com/services/login    
    ?username=demo
    &password=demo
    &returnProfile=true
{
  "serverVersion" : "6.1.1.622",
  "userProfile" : {
    "authorities" : [ "ROLE_USER", ... ],
    "username" : "demo",
    "fullName" : "Demo User",
    "userZone" : "/Users/demouser",
    "groups" : [ "department1" ],
    "email" : "user@example.com"
  },
  "loginSuccess" : true,
  "csrfToken" : "ababababababab"
}

Login failure

The following shows the response of a failed authentication attempt.

login
http://demo.elvisdam.com/services/login    
    ?username=guest
    &password=wrongpassword
{
      "loginSuccess" : false,
      "serverVersion" : "6.1.1.622",			
      "loginFaultMessage" : "Invalid username or password"
    }

Document history

  • 21 September 2017: Updated the section 'POST requests only'.
  • 21 September 2017: Updated section 'What does it do?' with a link to the REST API login article.
  • 27 July 2017: Added section 'Post requests only'.
Was this article helpful?
0 out of 0 found this helpful / Created: / Updated:
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.