API authentication
- Kiss, Mate
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 |
|---|---|---|
| API Key | Random generated, unique GUID. | - |
| Name | Name of the API key. | Required field |
| 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:
Detailed description of the API request elements:
| 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: