Skip to content

Security and authentication

MiaRec REST API requests are secured by the following methods.

Authentication

Every request must carry a valid user name and password in the HTTP Basic Authentication header. Requests without valid credentials are rejected with 401 Unauthorized.

The user is a regular MiaRec user account, created in the web portal. The account must meet the following requirements:

  • Its role has the REST API permission enabled (the rest_api resource with the allow action in the role's permissions dictionary). See Roles and permissions.
  • Its authentication type is password. Users who sign in through LDAP or single sign-on cannot use the REST API.
  • Web portal access is enabled for the account.

Example of authentication using curl:

curl -u {login}:{password} https://{your-miarec-server}/api/v2/users.json

Tip

Create a dedicated user account for each integration, with a role that grants only the permissions the integration needs. This keeps the audit trail readable and limits the impact of a leaked password.

Encryption

When accessing MiaRec REST API over public networks, use HTTPS so that user names, passwords, and contents are protected from snooping. The hosted platform accepts HTTPS connections only.

Role based permissions

The administrator configures which resources and operations are accessible to each role. When the role of the API user lacks the permission for a request, the API returns 403 Forbidden.

Records outside the access scope of the role (for example, calls of another group for a Selected Groups role) are not visible at all: lists omit them, and requests by ID return 404 Not Found. See Access scope.

Some attributes of a record are visible only to certain roles. For example, tenant_id, voip_protocol, and recorder_id of a call are returned only to administrators of the System tenant.

IP address restrictions

A role can restrict access to a list of IP addresses or networks. A request from an address that is not allowed is rejected with 403 Forbidden, even when the credentials are valid.

Protection against password guessing

After three failed sign-in attempts for the same login from the same IP address, the API delays further attempts. The delay grows by 15 seconds with every additional failure and is reported in the Retry-After header of a 429 Too Many Requests response. The counter is reset by a successful sign-in. A separate, higher limit applies to all failed attempts from one IP address.

Store the credentials in your integration correctly and do not retry a rejected request with the same password, otherwise the integration locks itself out.

Request rate limits

The service provider can limit the number of API requests per minute and per day for each tenant. See Rate limits.