Welcome to the documentation and reference page of the EVVA AirKey Cloud API. Our REST API provides the customer with powerful control of his AirKey infrastructure from any third-party application.
These features can be controlled via API:
Some components of AirKey cannot be controlled through the API, as they have no internet connection. This concerns mostly parts which are set up only once:
You need to generate a secret API key to access the API. The key is sent through a HTTP header (X-API-Key) every time you access the API. Beside the production API, we provide a test environment for development purposes. Here you can try out all API features in a safe sandbox-like environment.
To activate the API open the AirKey Online Administration at https://airkey.evva.com in your web browser. Go through the "AirKey registration" process if you haven't registered yet. Then log in and choose "Settings".
The test environment is free of charge. A predefined set
of test data can be loaded and reset to the intial state anytime.
Please note that it is not possible to access the test environment's
data in the AirKey Online Administration.
Furthermore no real SMS text messages will be sent in the test environment.
To activate the test API go to "Settings" →
"AirKey Cloud Interface (API) – test environment"
and select "Generate the API key".
Immediately write down the API key, as it is displayed only once for security reasons.
You can reset the provided test data to the predefined data set anytime by clicking on "Reset test data" or by sending the "/v1/public-mgmt/reset-test-data" request via the API.
To activate the actual production API click the "Activate API" button (350 credits needed). After the activation you can generate your secret API key. The key is displayed only once. Use this key instead of the test API key to switch from testing to production operation.
Attention, you are now working with real production data!
In case of problems, please try to repoduce them in the test environment before contacting support.
There are several ways in which you can access the EVVA AirKey Cloud API:
The easiest way to perform requests is by using the built in "Try it out" feature of the Swagger Documentation below. First click on "Authorize" and enter your API key. Then you can use the "Try it out" button next to each request.
Another convenient option is to use a tool like Postman.
To access AirKey directly from your application you have two main options: You can simply send direct request with tools like "curl" and handle the requests yourself, or you can use generated classes for your programming language via the Swagger Generator.
Here is a short run-down of how to use Swagger Generator:
{
"spec": {},
"options": {},
"swaggerUrl": "https://integration.api.airkey.evva.com/docs/swagger.json"
}
Please note that EVVA cannot provide any implementation support for the API. Contact your software development, agency or vendor for support.
In the following we provide some general information about the usage of the API:
Below you can find the extensive Swagger Documentation for all request types and models (objects). Information about the request URLs, query parameters, request body configuration, examples of body and response, as well as valid response codes are provided there.
For body and response you can click on the "Model" link to get information about the
fields. Provided are details about data type, required (marked by a red asterix) and read only.
Note that you can expand child models by clicking on them.
Example: GET /v1/persons → Responses → Model
→ personList (click on the right angle bracket) → Person
→ correspondenceLanguageCode (click on the right angle bracket)
For each request a valid API key must be sent in the HTTP header (name "X-API-Key"). To generate a new API key, see section "API Activation".
JSON notation is used throughout the API:
Make sure to properly apply URL encoding for query parameters according to RFC 3986.
Most GET requests use paging. Per default 20 entries are returned. You can retrieve up to 100 entries by giving the "limit" query parameter.
Example: /persons?limit=100
Subsequent pages are loaded via the "offset" query parameter.
Example to load page two: /persons?limit=10&offset=2
If you want to update an existing object you should retrieve it first via GET request, modify the values as you wish, and then perform a PUT request.
The reason for that is that many PUT requests require to add the current version of the object. This is important to avoid concurrent modifications and overrides.
Please note that you have to give all required fields, even if they are read only.
Currently supported:
Timestamps are generally provided in ISO 8601 date and time format, with time in UTC and millisecond precision. The UTC timezone is defined by the letter "Z" (for zero meridian) in the last position. Seconds and milliseconds are optionally.
Example: 2019-05-09T09:25:36.608Z
Date fields which hold only the date without time follow a naming convention with "Date" suffix.
Example: "validFrom" (date + time) vs. "validFromDate (only date)
Attention: Timestamps for authorizations are given without timezone (without letter "Z" in the last position), because locks work in the local timezone and need times relative to their time zone. For example you want to provide access to a door at 4:00 p.m. in the time zone of the lock, and not at 4:00 p.m. UTC.
Example: 2019-05-09T09:30 /* without letter "Z" in the last position */
Furthermore authorization timestamps take only certain minute values and no seconds or milliseconds.
Valid minute values for authorization: 00, 05, 10, 15, 20, 30, 40, 45, 50, 55
The API uses the following naming convention regarding IDs:
The translation fields for protocol responses contain various CSS class definitions. The necessary files for human friendly representation for these fields are:
In this section we give you a short introduction of a common authorization life cycle.
You can also try out and inspect these requests in our
API Demo App.
The simplest way to create an authorization for a smartphone is to use the convenient "/send-a-key" request. This is a single simplified interface for multiple requests in the background: create a person, create a "phone" medium, assign the medium to the person and create an authorization for the phone to the given lock (or area) and time.
To update data from the previous "/send-a-key" request you need to perform separate update requests for the involved data models:
POST /v1/authorizations/simple
{
"authorizationInfo": {
"type": "SIMPLE",
"validFrom": "2019-05-15T09:50",
"validTo": "2019-06-21T09:00"
},
"mediumId": 253,
"lockId": 140023087,
"removeAllExistingAuthorizationsForPair": true
}
Explanation: We logically create an authorization of type "SIMPLE" which takes only "validFrom" and "validTo" timestamps, and the IDs of medium and lock. Afterwards it is checked against all existing authorizations.
Additionally we give the option "removeAllExistingAuthorizationsForPair" in case of a necessary authorization change, applying on the current medium–lock pair. Meaning:
This request is also possible for an area. Use in this case "areaId" instead of "lockId".
If you want to delete all data created by a "/send-a-key" request you have to perform the following steps in the correct order:
POST /v1/media/{mediumId}/empty
Removes all authorizations from a medium.
POST /v1/media/cancel-assignmentTakes the {mediumId} as body and unassigns the medium from the person.
DELETE /v1/media/phonesTakes {mediumId} as body and removes the phone entry.
DELETE /v1/personsTakes {personId} as body and removes the person entry.
A lot of additional information can be found in the AirKey System Manual.
Please contact your EVVA partner for AirKey support inqueries.