Detailed Description

Login API

Overview

This is an authentication API for accessing the knowledge base resources. The server authenticates the given login username and password and creates a new egain session ID for the requesting user.
This eGain session ID can be then used in the subsequent user requests.
Session ID, once expired, cannot be used again and a new session ID can be created by using this API.

Since: 11.6

Schemas used

API

Method	URI	Description
POST	/ws/v12/authentication/user/login	Authenticates user's login request and creates a new session ID.

Request

Request headers

Name	Description
Content-Type	application/xml or application/json
Accept	application/xml or application/json
Accept-Language	Optional header that is used to specify the language of error messages. Default value is the primary KB language assigned to the user. See Supported 'Accept-Language' header language codes.

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	Type
username	Login user name.	String
password	Password for the above user name.	String

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 user. The sixth request will fail, unless this parameter is sent along with the request. If this parameter is sent, the earliest session is terminated and a new session is created.

Supported common query parameters

None

Request body XML schemas:

Login Schema

Response

The response includes HTTP status code and headers only. No response body.

Success Status Code

204 - No Content

User successfully authenticated and a new session ID generated.

Failure Status Code

400 - Bad Request

User name not present in request body.
Password not present in request body.

401 - UnAuthorised

Invalid username in request body.
Invalid password in request body.

406 - Not Acceptable :

Invalid value of Accept-Language header.

500 - Internal Server Error

Response headers

Name	Description
Content-Type	application/xml or application/json
X-egain-session	Newly generated session ID

Response body

No response body is returned on successful authentication.

Error body schema

An error body is returned when the user request could not be successfully processed.
Different error codes returned by this API are listed in the 'Failure Status Code' section.

Error Response Schema

Examples

Example 1

Request

Method	URI	Description	Http Code Returned
POST	/ws/v12/authentication/user/login	Assuming the user request is successfully processed, a 204 success code is returned. No response body is returned by the server in this case.	204

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Login xmlns="http://bindings.egain.com/ws/model/v12/gen/platform">
	<userName>kbagent1</userName>
	<password>egain123</password>
</Login>

Response

204 - No Content

Example 2

Request

Method	URI	Description	Http Code Returned
POST	/ws/v12/authentication/user/login?forceLogin=yes	Assuming the user request is successfully processed, a 204 success code is returned. This example also demonstrates using the query parameter 'forceLogin'.	204

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Login xmlns="http://bindings.egain.com/ws/model/v12/gen/platform">
	<userName>kbagent1</userName>
	<password>egain123</password>
</Login>

Response

204 - No Content

Example 3

Request

Method	URI	Description	Http Code Returned
POST	/ws/v12/authentication/user/login	Below is the error response when user's credential, either username or password, could not be authenticated by the server.	401

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Login xmlns="http://bindings.egain.com/ws/model/v12/gen/platform">
	<userName>kbagent567</userName>
	<password>egain123</password>
</Login>

Response

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

Example 4 (Json)

Request

Method	URI	Description	Http Code Returned
POST	/ws/v12/authentication/user/login	Json request body.	204

{
   "userName": "kbagent1",
   "password": "egain123"
}

Response

204 - No Content