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.

Our first code example will connect us to our coreBOS install and retrieve a challenge string which we need to accomplish the final login. This code will later be included in all our examples to establish the connection each time. We include the necessary libraries: pear HTTP_Client, Zend JSON and an in house debugging class which will explicit all the communication going on if we need to see it. All of our examples will accept one parameter called 'debugcall', if this variable is set to one (1) all the communication information will be printed on screen. To get all this started you must point the $endpointurl to the location of your test coreBOS install and finally change the $userName if you are connecting as another user.

GetChallengeResult{
token:String //challenge string
serverTime:TimeStamp //time on server
expireTime:TimeStamp //expire time of token
}

http://corebos_url/webservice.php?operation=getchallenge&username=[username]

<?php
require_once 'HTTP/Client.php';
require_once 'Zend/Json.php';
require_once 'debugoutput.php';
 
// Debug messages
$dcall=$_REQUEST['debugcall'];
//url path to vtiger/webservice.php like http://vtiger_url/webservice.php
$endpointUrl = "http://localhost/ts521devel2/webservice.php";
//username of the user who is to logged in. 
$userName="admin";
 
$httpc = new HTTP_Client();
//getchallenge request must be a GET request.
$httpc->get("$endpointUrl?operation=getchallenge&username=$userName");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json)",$response);
 
//decode the json encode response from the server.
$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response",$jsonResponse);
 
//check for whether the requested operation was successful or not.
if($jsonResponse['success']==false) 
    //handle the failure case.
    die('getchallenge failed: '.$jsonResponse['error']['message']);
 
//operation was successful get the token from the response.
$challengeToken = $jsonResponse['result']['token'];
if ($dcall==1) printvar("Challenge token",$challengeToken);
?>

If you call this function you will see nothing on screen as we have just received a string value and saved it in the $challengeToken. Try executing it with debugcall=1 parameter in the browser.

Now that we have the challenge token we can proceed with the login step. If you look at the login parameters in the webservice reference guide you will see that we have to send the username and the access key, but the access key is not sent in plain text, it is sent encrypted (md5) and mixed with the challenge token obtained with the getChallenge call. This operation is executed as POST. Notice how this script includes the getChallenge script.

<?php
require 'dologin.php';
 
//listtypes request must be GET request.
$httpc->get("$endpointUrl?sessionName=$sessionId&operation=listtypes");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) listtypes",$response);
 
//decode the json encode response from the server.
$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response listtypes",$jsonResponse);
 
//operation was successful get the token from the response.
if($jsonResponse['success']==false)
    //handle the failure case.
    die('list types failed: '.$jsonResponse['error']['message']);
//Get the List of all the modules accessible.
$modules = $jsonResponse['result']['types'];
echo "<b>Accesible Modules</b><br>";
foreach ($modules as $modname) {
	echo "$modname<br>";
}
?>

As before this function does not return any output on screen unless we get an error or force output with &debugcall=1

Once these two steps have been taken we can continue by calling any of the webservice functions.

LoginResult{
sessionId:String //unique session identifier
userId:String //application user webserivce ID
version:String //Webservice interface version
vtigerVersion:String //coreBOS version
}

http://corebos_url/webservice.php?operation=login&username=[username]&accessKey=[accessKey]

• 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