Table of Contents
Login to Web Service
Access to the System
You need a valid coreBOS user to access the webservice. All the operations you can do through the REST interface will be limited by the coreBOS permission system of the connected user.
The REST API does not use the users password to connect. Instead it needs the user's access key which is a unique identifier created for each user that can be found in the user's preferences page.
The login operation establishes a session between the REST client and the coreBOS application, validates the user and returns a session identifier which must be used in all subsequent calls to coreBOS.
This login process is done in two steps, first we ask coreBOS for a challenge sequence and then we use the returned string to encode our access key for the final validation.
Get Challenge
| Purpose: | get a challenge string to encode the password for login |
|---|---|
| Profile: | getchallenge(username:String):GetChallengeResult |
| Send Type: | GET |
| Parameters: | username: name of an active and valid user in coreBOS |
| Returns: | A GetChallengeResult object with the challenge token and it's time to liveGetChallengeResult{
token:String //challenge string
serverTime:TimeStamp //time on server
expireTime:TimeStamp //expire time of token
}
|
| URL Format: | http://corebos_url/webservice.php?operation=getchallenge&username=[username] |
Login
Now that we have the challenge token we can proceed with the login step. For this we have to send the user name and a verification string. This verification string can be constructed in two ways:
- as an md5 encrypted string of the challenge token plus the user's access key
- as a concatenation of the token string plus the user's password this is insecure and NOT recommended
This operation is executed as POST
| Purpose: | Validate the user's access in the web service interface. The use of the getchallenge token is required |
|---|---|
| Profile: | login(username:String, accessKey:String):LoginResult |
| Send Type: | POST |
| Parameters: | username: name of the active coreBOS user that needs access accessKey: [token+password|md5(token+accesskey)] |
| Returns: | A LoginResult object with the session identifier and some additional informationLoginResult{
sessionId:String //unique session identifier
userId:String //application user webserivce ID
version:String //Webservice interface version
vtigerVersion:String //coreBOS version
}
|
| URL Format: | http://corebos_url/webservice.php?operation=login&username=[username]&accessKey=[accessKey] |
| Comments: | The accessKey parameter is written with a capital 'K' The user's access key can be found on the user's profile screen inside the application |
Once these two steps have been taken we can continue by calling any of the web service functions.
Logout
| Method: | logout |
|---|---|
| Purpose: | The logout service eliminates the session information, invalidating any further operations with that session ID. For security reasons this method should be called when the user of the external application finishes his tasks. He should have an option to close the application. |
| Profile: | logout(sessionId:string):Map |
| Send as: | POST |
| Parameters: | ⇒ sessionId: session ID to invalidate. |
| Response: | map with one entry: successfull |
More Information
- This method of authentication is called Challenge-Handshake Authentication Protocol and it is more secure than a username/password authentication. Read here for more information
