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 an 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 it 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 the API Keys permission.
| 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 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 the System Administrator and System Supervisor roles. | - |
Simple, API key only based authentication
For applications with a limited set of capabilities, where e.g. only a single HTTP GET request can be issued by calling an 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 will return times in GMT.
Request token
The external application sends an authentication request via HTTP GET or POST and provides the login and password in a Basic Authorization header:
The Authrozation header starts with the "Basic" string, followed by a space character, then the Base64 encoded form of the login and password separated by a colon, in the above example the "myapiuser:pa$$word" was sent in the Base64 encoded format.
Alternatively, the login and password can be sent in the userName and password HTTP parameters too. It is important that the MD5 format is no longer supported, the password has to be sent in clear text format, so this type of authentication is highly not recommended for GET requests.
Detailed description of the API request elements:
| API request element | Description | Requirements |
|---|---|---|
| /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 |
| Authorization: Basic bXlhcGl1c2VyOnBhJCR3b3Jk | The Basic Authorization header with the Base64-encoded login:password string. The provided user has to have System Administrator and System Supervisor roles. | Mandatory |
| userName=myapiuser | If Basic Authorization is not supported by the client, then the Login ID of the user. | Mandatory |
| password=pa%24%24word | If Basic Authorization is not supported by the client, then the Password of the user (the "pa$$word" string in URL-Encoded format) | Mandatory |
Response
On success, the API responds with the followings: