Session Life Cycle

Each REST API call by a client is associated with a web service session. A session is created when client calls Login API and stays active until it times out or is logged out. When the session is created, a session ID that looks like a GUID is generated and assigned to it by the server. It is returned to the client in an HTTP header called X-egain-session. This header, like all HTTP headers, is case insensitive.

All ECE REST API require authenticated access. Therefore, the first call made by a client must be to the Login API. The client then must record X-egain-session HTTP header returned in the response and submit this header in the subsequent calls. The header containing session ID is passed back and forth from the client to the server during the session.

The only APIs that do not require X-egain-session header are Login API and various .../hello APIs. If the header is not present in an incoming call for the rest of ECE REST API, the REST API will return 401 'Unauthorized' error response.

Handling a 401 Response

There are a number of scenarios where a 401 response may be received:

session times out and the client attempts to use the session ID again;
invalid session ID is supplied with the request;
no session ID is supplied with the request (the client either did not login or did not record the session ID returned by the server);
wrong user credentials are supplied to Login API.

To distinguish between the cases listed above, the client can check the 'message' field of the response body:

For Knowledge APIs for Authoring:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Error xmlns="http://bindings.egain.com/ws/model/v12/gen/platform">
   <message>User could not be authenticated. Invalid session ID.</message>
</Error>

For Interaction APIs:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<error xmlns="http://bindings.egain.com/ws/model/v12/gen/common">
   <code>401-101</code>
   <developerMessage>Invalid or expired 'X-egain-session' header provided. New login is required.</developerMessage>
</error>

If 401 response is received from the server, the client should call Login API with valid user credentials.

Using ECE REST APIs From ECE Application Consoles

Starting with ECE 15, when a user logs into ECE application consoles and is successfully authenticated, the user is automatically logged in to make calls to the interaction and authoring REST APIs. If the user logs out from ECE console, she will be automatically logged out for that session from ECE REST API.

Upon successful authentication to ECE console, a session cookie containing the user's session identifier is created and set on the user's web browser. The name of this session cookie is X-egain-session. In addition, a token to prevent Cross-Site Request Forgery (CSRF) attacks is also created by the server. The name of this token is X-egain-csrf. The same session identifier and the anti-CSRF token can be used for making calls to ECE REST APIs.

In order to make REST API calls seamlessly from ECE application console, you need to pass the session identifier (X-egain-session) as well as anti-CSRF token (X-egain-csrf) with every API request.

X-egain-session needs to be sent in as a cookie. The cookie is sent automatically by the browser if the call is made from the same browser session.
X-egain-csrf needs to be sent in as a header. You need to explicitly send the X-egain-csrf header with the request. For your convenience, a utility JavaScript function getEgainSecurityToken has been provided to retrieve the value of this token. See my_activities.html file for details on how to use this function.

Example:

Copy my_activities.html file on your ECE application installation's web server in EGAIN_INSTALLATION_FOLDER/web/custom/view folder.
Login as a partition administrator, and add a new custom Information pane from the Tools Console. Set the launch URL to: http://WEB_SERVER_ADDRESS/CONTEXT_ROOT/web/custom/view/my_activities.html.
Login to the Agent Console.
Go to the My Activities section of the Information pane. When this section loads, it will make an AJAX request to ECE REST API with X-egain-csrf request header, and browser automatically will send the X-egain-session cookie. This AJAX request makes a GET Activity API call to fetch all activities for the logged in user. Response is rendered in the Information pane.

In this example the following AJAX code snippet calls an ECE REST API using jQuery. Note that the X-egain-csrf request header sent in the request contains anti-CSRF token.

$(document).ready(function(){
    $.ajax({
        url:"../../../ws/v12/interaction/activity?assignedTo=" + userId,
        type:'GET',
        headers:{'X-egain-csrf':eGainCSRFToken,
            'Accept-Language':'en-US',
            'Accept':'application/json'},
        complete:function(xhr, status){
            if (status=='success' && xhr.status=='200')
            { 
               // Code to render the response
            }
        }
    }});
});