iThenticateDeveloperWebsite

Login

The login method is used to authenticate a session. A session is initiated by supplying valid authentication credentials (username and password) to the login method and a session id (sid) is returned that must be included when making additional requests.

Method Name: login

Arguments: username, password

Returns: sid, api_status, response_timestamp

Errors: Returns errors on unsuccessful login attempts. The error handling is split between the errors field and the messages field. Some possible combinations are:

• If the password is too short, an error will be present in the errors element indicating the password was too short, and no informational message will exist in the messages element.
• If the username was not a valid email address, an errors element will be presented indicating that fact, and no informational message will exist.
• The existence of errors is usually accompanied by a status code of ‘500’. 

Messages: Unsuccessful login attempts may also return error messages in this messages element. Some possible messages are as follow:

• If the username was of the correct form, but does not exist in the system, the generic message “Sorry, failed to log in.” will be returned in the messages element. This error message (in the messages element, NOT the errors element) will also be returned if the username was valid and the password was incorrect (note that this will not be the case for an INVALID password, one that is too short or does not contain the characters needed for a valid password).
• If the API client has not been authorized to connect with the IP address it is using, the error message (in the messages element, NOT the errors element) will be Access denied from 127.0.0.1”, with the invalid IP address presented in the message
• (127.0.0.1 used as an example).
• Multiple messages may be presented, for situations where invalid username/password combinations are submitted, as well as invalid access attempts. However, both errors and messages will not be presented simultaneously (the API client MUST examine all possible combinations of messages and errors, except for messages and errors simultaneously, to determine if an error condition exists). However, as a convenience approach, checking for the existence of the sid element is usually sufficient to guarantee a successful login. 
• The existence of (error) messages is usually accompanied by an api_status element value of ‘401’.

Example Request

Example Response