API authentication

In order to access the services of the API, external applications have to authenticate themselves. Since, there are external applications with limited functionality, the Verba Business API offers a simplified authentication mechanism as well, but for better security we strongly recommend to use the normal authentication mechanism implemented in the API. As a part of the authentication process, the system only accepts requests, which contain a pre-generated API key. The system supports unlimited number of API keys, which can be issued through the web interface.

API key administration

An API key identifies an application that is intended to use the Verba Business API. The API key administration is available on the web based user interface of the system. In order to access the configuration, please navigate to Administration / API Keys.

Each application should have its own API key so that they can be configured separately.

API key parameters

You can configure the API keys on the web interface of the Verba Recording System if you have System Administrator rights.

Field	Description	Requirements

Field	Description	Requirements
API Key	Random generated, unique GUID.	-
Name	Name of the API key.	Required field Minimum length: 3 Maximum length: 128
Network Restrictions	For each API key, the system can restrict the access to the API for a certain set of network addresses. This optional parameter contains a list of IP addresses and/or hostnames.	-
Requires Authentication	If this flag is enabled, the external application has to provide user credentials before accessing the functions of the API. The provided user has to have System Administrator and System Supervisor roles.	-

Simple, API key only based authentication

For applications with limited set of capabilities, where e.g. only a single HTTP GET request can be issued by calling a HTTP URL, only the API key has to be provided in each API request.

Enhanced, user account based authentication

For better security, the external application has to provide user credentials in order to access the API.

The security tokens' lifetime is 1 hour. The timezone of the results will match the user time zone if user authentication is required for the API key. Unauthenticated API calls with return time in GMT.

Request token

The external application sends an authentication request via HTTP GET or POST:

http://192.168.1.104/verba/api?action=RequestToken&apiKey=74c8eea0-50c6-40b2-9f3e-252ed501c3c8&userName=ApiUser&password=a7a3c5b8c9ab164b64afb70473e8a3c1

Detailed description of the API request elements:

API request element	Description	Requirements

API request element	Description	Requirements
http://192.168.1.104/verba/api	Verba Business API HTTP URL.	Mandatory
action=RequestToken	Name of the HTTP API request.	Mandatory
apiKey=74c8eea0-50c6-40b2-9f3e-252ed501c3c8	API key used to identify the application.	Mandatory
userName=ApiUser	Login ID of the user. The provided user has to have System Administrator and System Supervisor roles.	Mandatory
password=a7a3c5b8c9ab164b64afb70473e8a3c1	MD5 hash code of the password of the user.	Mandatory

Response

On success, the API responds with the followings:

<?xml version="1.0" encoding="UTF-8"?>

</VerbaApi>