Detailed Description

Login Customer

Overview

This is an authentication API, which can be used by customers to log in to the application. Once authenticated, the customers can access Interaction APIs as well as Access APIs using the same session ID that is returned as part of the authentication.

Session ID, once expired, cannot be used again and a new session ID can be created by using this API.

Since

15.0.2

APIs

Method	URL	Description
POST	`/ws/v15/context/authentication/user/login`	Authenticates customers logging into the application.

Permissions

Licenses

Each of the below licenses will be consumed as part of this API. Hence, these must be installed and available for consumption:

ECE Selfservice + AI

Request

Request headers

Name	Description	Allowed values	Default value
Content-Type	Media type sent by the client.	`application/xml` or `application/json` or `multipart/form-data`	N/A
Accept	Content type accepted by the client.	`application/xml` or `application/json`	N/A
Accept-Language	Language locale accepted by client (used for locale specific fields in resource representation and in error responses)	Supported 'Accept-Language' header codes	`default system language`

Request Body

The request body is mandatory. Request body can be in either XML or JSON format.

Elements required in the request body

Name	Description
userName	Login ID of the customer
password	Password corresponding to the login ID

Optional elements allowed in the request body

None

Supported API specific query parameters

Name	Description
forceLogin	This is an optional query parameter. The only possible value is "yes". In the application, a maximum of 5 concurrent sessions are allowed for a customer. The sixth request will fail, unless this parameter is sent along with the request. If this parameter is sent by the client, the earliest session is terminated and a new session is created.

Supported common query parameters

None

Request body XML schemas:

Login Schema

Response

Response headers

Name	Description	Possible values
X-egain-session	Newly generated session ID	N/A
Content-Type	Media type of response body	`application/xml` or `application/json`

Response body XML schemas:

Error - used in case of error

HTTP status codes

Success Status codes

204 - No Content

The customer was successfully authenticated. The new session identified will be sent as part of the response header "X-egain-session".

Failure Status codes

400 - Bad Request

Any unsupported query parameter is sent in the request.
The value of any of the query parameter is unsupported.
Request body does not contain the required elements.
An unsupported element is present in the request body.
Request body is empty.

401 - Unauthorized

If the customer cannot be authenticated using the supplied credentials.

403 - Forbidden

If the user with username provided in request body currently has 5 active web service sessions and forceLogin query parameter with value "yes" is not sent in the request.

500 - Internal server error

Examples:

Example 1 - Login a customer
Example 2 - Login a customer with forceLogin query parameter