To invoke Servitly APIs from third-party systems, the Servitly backend is expecting a valid API Key used to identify the remote client. Before dealing with APIs, you need to create an API Key.

Creating API Key

In order to create a new API Key, you must follow these steps:

Enter the Integration / API Keys page.

Click on the Create API Key button.
A new API Key will be added to the list of all API Keys.
Complete the API Key configuration by defining constraints and permissions.

Restrictions

The restriction section allows defining a filter protecting against unauthorized usage. It is possible to define a valid source domain (e.g *.acme.com) or a valid mobile application package name (e.g. com.acme.mobile.app).

Permissions

Within the Permissions section, you can specify the permissions to limit the operations a client can perform via API. When using an API key, user permissions are further restricted according to the permissions associated with the API key.

For more details about available permissions, refer to the User Permissions article.

Using an API Key

To correctly use an API Key, once obtained, the client must use it during the login service call:

/identity/users/login?apikey=37b51d19467513e45b56f7824f2d51f2

Web Client

The caller is verified by inspecting the HTTP referer header, which must match the domain specified within the key restriction.

Referer: https://www.mysite.com

Mobile App

The caller is verified by inspecting the HTTP User-Agent header, which must end with the Android package name or iOS app identifier.

User-Agent: Mozilla/5.0 My Browser; com.acme.mobile.app

If an API Key is deleted, all the clients using it will be no longer able to call the Servitly API.

Restrict access to only one device per user

In case of Mobile App Restriction, you can also select whether the access can be made from only one mobile device per user at a time. If selected, when a user performs the login from a mobile device, he is automatically logged out from other mobile devices. Push notifications will also be turned off on the devices where the automatic logged-out occurs.

Rate Limit

The whole DPS is limited in the number of maximum requests per hour a remote client can perform through REST API, this limit depends on the agreement between the Manufacturer and Servitly.
Moreover, in case an API key must be used by a third party client, it is possible to set a rate limit that avoids consuming all requests available on the tenant.

For instance, if the tenant has a limit of 500 requests/hour, it is possible to configure 5 API keys with a rate limit set to 100 requests/hour. But in case the total amount of requests/hour exceeds 500, all the clients will be blocked for a while until a new buffer of requests is available.
For these reasons, be careful defining the rate limits according to the whole tenant rate limit.