Content Comparison

...

Configuration Article | CA-20220907-TP-01 VDG Sense | API | Usage Image Added

View file name CA-20220907-TP-01.pdf

The HTTP interface can be operated by sending HTTP/1.1 compliant requests and retrieving their responses. Requests consist of a single file request, with optionally HTTP/GET parameters and can contain optional HTTP/POST XML data. All responses sent by the HTTP interface will contain XML HTTP/POST data. The following three files are relevant to user authentication, where [server] is the reachable address of manager:

...

API version 2.6.1 and above contain the /info request file. When called, this request will return the following response:

<?xml version="1.0" encoding="UTF-8"?>
<apiinfo>
    <utc>[current time on the server]</utc>
    <version>[api version]</version>
</apiinfo>

For example, a /info request made on the date and time above on version 2.6.1 will return the following response in its HTTP/POST data

<?xml version="1.0" encoding="UTF-8"?>
<apiinfo>
    <utc>2013-09-03 19:05:55<!-- utc-->
    <version>2.6.1</version>
</utc></apiinfo>
</apiinfo>

Take note that earlier versions of the API will return a 404 NOT FOUND error when requesting /info. Use this to work out that the 2.6.1 features are not available. A /info request does not require authentication.

...

The digest authentication method uses a so-called ‘nonce’ to identify the type of client that connects. An example message of the digest authentication method is:

<?xml version='1.0'?>
<AuthenticateUserDigest>
    <username>user</username>
    <nonce>AR5chsWVZagPfMpB</nonce>
    <timestamp>2013-09-04 08:38:43</timestamp>
    <digest>804a2cba7610088a6c7975777e6349daefadcdf9</digest>
</AuthenticateUserDigest>

In this message, the nonce identifies the client type. These nonces will be given to API integrators based on the type of connection they will use. The timestamp is the current time in UTC. The digest is a digital signature to verify the message contents. Note that there is no password field. The password is used when the digest string is created and this string contains enough information for the API to verify that the sender of the message knows the correct password.

...

PHP example of digest calculation

// User input, generated time and app nonce
$username  = "user";
$password  = "password";
$timestamp = gmdate("Y-m-d H:i:s"); // e.g. 2013-09-04 08:38:43
$nonce     = "AR5chsWVZagPfMpB";
 
// Note that the result of the first sha1 is binary.
$string = md5( $timestamp ) . $username . sha1( sha1( $password, true ) );
 
// Note that $nonce is used as data and $string as key.
$digest = hash_hmac( "sha1", $nonce, $string );

Response

If the authentication was successful, the system will respond with a session key. Include this in further requests which require authentication. The following is an example of a successful login response.

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticateUserDigestResponse>
    <result>OK</result>
    <sessionkey>275000862</sessionkey>
    <apiversion>2.6.1</apiversion>
</AuthenticateUserDigestResponse>

In case of error, the system will respond with an error string as seen below.

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticateUserDigestResponse>
    <result>ERROR</result>
    <message>Authentication failed</message>
</AuthenticateUserDigestResponse>

Basic authentication

Servers using an API version prior to 2.6.1 (which does not support /info) can be reached by using basic authentication. Mobile notifications are not supported using this version. A basic authentication request is also sent to the /webservice file and looks as follows:

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticateUser>
  <username>[username]</username>
  <password>[plain-text password]</password>
</AuthenticateUser>

In case of success, the webservice will return a session key, which can be used for other methods. In case of error, the webservice will return an error string.

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticateUserResponse>
    <result>OK</result>
    <sessionkey>275000862</sessionkey>
    <apiversion>2.3.1</apiversion>
</AuthenticateUserResponse>

Logging out

Both digest and basic authentication methods use the same logout request. A logout request is sent to the /webservice file and looks as follows:

<?xml version="1.0" encoding="UTF-8"?>
<DeleteSessionKey>
  <sessionkey>[sessionkey]</sessionkey>
</DeleteSessionKey>

If the user has been logged out successfully, the webservice will return OK. An error string is returned otherwise.

<?xml version="1.0" encoding="UTF-8"?>
<DeleteSessionKeyResponse>
  <result>OK</result>
</DeleteSessionKeyResponse>