{"type":"doc","content":[{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":1200,"id":"3829f343-513b-4bdd-9519-00403ee09c0d","collection":"contentId-9167405095","type":"file","height":432}}]},{"type":"table","attrs":{"layout":"default","localId":"853c89e1-e260-4a1d-8312-d6ede02db674"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[486.0]},"content":[{"type":"paragraph","content":[{"text":"Configuration Article | CA-20220907-TP-01","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"VDG Sense | API | Usage","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":15.0},"content":[{"type":"media","attrs":{"width":800,"id":"a6902773-77c1-45a1-888c-781a373698be","collection":"contentId-9167405095","type":"file","height":126}}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[160.0]},"content":[{"type":"mediaGroup","content":[{"type":"media","attrs":{"id":"84595600-e15a-475c-88fe-d8dc38ebec17","collection":"contentId-9167405095","type":"file"}}]}]}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"bee0189a-a317-4216-8380-00faae5f1e68"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"da081f04-c143-4c98-997d-5b5085d3d85f"}},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"http://[server]/info","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"http://[server]/webservice","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"http://[server]/command","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"In addition, some request and responses contain a UTC timestamp. These timestamps are formatted as follows: yyyy-mm-dd hh:mm:ss. For example, 2013-09-03 19:05:55 represents 5 minutes and 55 seconds past 7 p.m. on the 3rd of September 2013 in UTC time.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Retrieve server-side information","type":"text"}]},{"type":"paragraph","content":[{"text":"API version 2.6.1 and above contain the /info request file. When called, this request will return the following response:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"1d47f747-e0e7-4ce3-8e7f-9061bb5a6ba9"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1,"colwidth":[680.0]},"content":[{"type":"codeBlock","content":[{"text":"\n\n [current time on the server]\n [api version]\n","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"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","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"cf2d8e02-009e-4092-8da5-bb508fcfd0b2"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1,"colwidth":[680.0]},"content":[{"type":"codeBlock","content":[{"text":"\n\n 2013-09-03 19:05:55\n 2.6.1\n\n","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Digest authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"4174e688-a407-45f4-9749-c1eaa887f4fd"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1,"colwidth":[680.0]},"content":[{"type":"codeBlock","content":[{"text":"\n\n user\n AR5chsWVZagPfMpB\n 2013-09-04 08:38:43\n 804a2cba7610088a6c7975777e6349daefadcdf9\n","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Digest calculation","type":"text"}]},{"type":"paragraph","content":[{"text":"This section describes how to calculate the digest string. First, some input values need to be determined: username, password, current time and the nonce.","type":"text"}]},{"type":"paragraph","content":[{"text":"USR: user","type":"text"},{"type":"hardBreak"},{"text":"PWD: password","type":"text"},{"type":"hardBreak"},{"text":"TIME: 2013-09-04 08:38:43","type":"text"},{"type":"hardBreak"},{"text":"NONCE: AR5chsWVZagPfMpB","type":"text"}]},{"type":"paragraph","content":[{"text":"With the time, username and password, the following string can be formed:","type":"text"}]},{"type":"paragraph","content":[{"text":"MD5(TIME)+USR+SHA1(SHA1(PWD)) = a268f1c72dea7d9d677e365d1285fd78user2470c0c06dee42fd1618bb99005adca2ec9d1e19","type":"text"}]},{"type":"paragraph","content":[{"text":"In other words, this means that the resulting string is a concatenation of an MD5 hash of the time string, the username and a double SHA1 hash of the password. Note that the input for the second SHA1 calculation uses the binary result of the first one, not its string representation. This string and the nonce are then used to create the final message authentication code with HMAC-SHA1. The string should be used as key and the nonce should be used as data in the HMAC-SHA1 function.","type":"text"}]},{"type":"paragraph","content":[{"text":"DATA = AR5chsWVZagPfMpB","type":"text"},{"type":"hardBreak"},{"text":"KEY = a268f1c72dea7d9d677e365d1285fd78user2470c0c06dee42fd1618bb99005adca2ec9d1e19","type":"text"},{"type":"hardBreak"},{"text":"HMAC-SHA1 (DATA, KEY) = 804a2cba7610088a6c7975777e6349daefadcdf9","type":"text"}]},{"type":"paragraph","content":[{"text":"The resulting string can be used as the digest field in the authentication message. The authentication message should be sent to the /webservice request file.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"PHP example of digest calculation","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"bd9a873c-57b2-40c3-b0cb-094c065a7f0f"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1,"colwidth":[680.0]},"content":[{"type":"codeBlock","content":[{"text":"// User input, generated time and app nonce\n$username = \"user\";\n$password = \"password\";\n$timestamp = gmdate(\"Y-m-d H:i:s\"); // e.g. 2013-09-04 08:38:43\n$nonce = \"AR5chsWVZagPfMpB\";\n \n// Note that the result of the first sha1 is binary.\n$string = md5( $timestamp ) . $username . sha1( sha1( $password, true ) );\n \n// Note that $nonce is used as data and $string as key.\n$digest = hash_hmac( \"sha1\", $nonce, $string );","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Response","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"eca2e920-9d6b-4ce2-8606-09f65314a502"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1,"colwidth":[680.0]},"content":[{"type":"codeBlock","content":[{"text":"\n\n OK\n 275000862\n 2.6.1\n","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"In case of error, the system will respond with an error string as seen below.","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"c6f98510-b672-4783-baa7-ac23c845e012"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1,"colwidth":[680.0]},"content":[{"type":"codeBlock","content":[{"text":"\n\n ERROR\n Authentication failed\n","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Basic authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"cab44702-71ff-4343-a830-1bda2d2ca3e5"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1,"colwidth":[680.0]},"content":[{"type":"codeBlock","content":[{"text":"\n\n [username]\n [plain-text password]\n","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"42aa1c00-f610-4549-8f40-900659b31fe1"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1,"colwidth":[680.0]},"content":[{"type":"codeBlock","content":[{"text":"\n\n OK\n 275000862\n 2.3.1\n","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Logging out","type":"text"}]},{"type":"paragraph","content":[{"text":"Both digest and basic authentication methods use the same logout request. A logout request is sent to the /webservice file and looks as follows:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"b010d506-e1a2-478c-a690-4894d50d5c4e"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1,"colwidth":[680.0]},"content":[{"type":"codeBlock","content":[{"text":"\n\n [sessionkey]\n","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"If the user has been logged out successfully, the webservice will return OK. An error string is returned otherwise.","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"1b740bfb-9580-4b97-8733-a2d8d3492df9"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"initial","rowspan":1,"colwidth":[680.0]},"content":[{"type":"codeBlock","content":[{"text":"\n\n OK\n","type":"text"}]}]}]}]},{"type":"paragraph"}],"version":1}

Browser not supported