October 2024

• API key authentication is now deprecated. We recommend migrating your integration to OAuth. API keys will stop working in a future date.
• Expanded "Integration examples" section.
• Expanded documentation of endpoint POST /members/:id/pins.

September 2024

Added device to the API. One highlight is this now allows obtaining the online/offline status and battery level of devices via the API.

• Added endpoints /devices
• Added endpoints /products
• Added device_id to /gadgets.
• Added webhook signatures.
• Expanded documentation for events.
• Expanded documentation for webhook filters.

June 2024

• Added /members/:id/cards endpoints.

April 2023

• Added support for creating, editing, deleting member_groups.

October 2021

• Added /members/:id/pins endpoints.

July 2020: Version 2.0

• Members can now have multiple email addresses.
• Members can now have multiple magic links.
• A member can have email addresses and magic links at the same time.
• A member can now be associated to multiple groups, with each association having its own start and end date/times.

Having multiple email addresses is useful for hotel room reserves where you have multiple guests in the same room. Now you can create the reserve as a single member that grants access to all guests.

Per-group start/end times is useful for room reservations: the same member can have multiple reservations for different rooms at different times, and he'll only be able to enter each room during the allowed time.

API changes

• Removed member fields: type, email, member_group_ids
• Removed endpoints /members/{member_id}/magic_link
• Added endpoints /members/{member_id}/emails
• Added endpoints /members/{member_id}/magic_links
• Added endpoints /members/{member_id}/group_associations

Version 1.0

Initial API release

The major version is indicated in the URL. For example https://api.akiles.app/v2 vs https://api.akiles.app/v2. The minor version is not indicated anywhere, since minor versions only do backwards-compatible changes. A client designed for API version v2.0 should work unmodified on version v2.1, provided it follows the compatibility policy outlined below.

We will release new minor versions with only backwards-compatible changes. We consider the following changes backwards-compatible:

• Adding new endpoints.
• Adding new HTTP methods to existing endpoints.
• Adding new optional fields to request objects.
• Adding new fields to response objects.
• Adding new possible values to enum fields.
• Relaxing request validation rules. For example, a field couldn't be null before and now it can.

Keep these in mind when developing your integration. For example, when parsing API responses, ignore unknown received fields instead of erroring.

Ocasionally, when backwards-incompatible changes are necessary for the healthy evolution of the platform, we will also release new major API versions. In this case, the previous major version will be supported for at least 6 months after the launch of the new major version.

There are many ways of integrating Akiles into your existing platform or service. There are two main categories:

• Sync integration (non whitelabel): The user end user will login with the Akiles app or website (magic link, without downloading any app). You can still customize and change all the related paramenters such as member validity, permissions, sites, etc. The integration consists in syncing your existing objects (users, reservations) with Akiles so user creation and management can be fully automatic.

• Whitelabel integration: The end user will be able to access the diferent spaces through a custom experience in your app or website. You can implement any logic that will end up opening a door. This integration has extra cost and is only available with the whitelabel feature. If you plan to publish your integration and make it available to all Akiles customers, we suggest you to use the non whitelabel option.

Sync integration (non whitelabel)

In this kind of integration, the user will use the Akiles app and environment to interact with your spaces. The idea behind this integration is directly creating or editing other Akiles objects from your backend as needed. You will be able to create, edit and delete members or any other object or parameter based on your business logic.

The end user will have to login once the required member is created using any of the valid login methods. You will have to use the already flexible Akiles permission system to implement your logic.

This kind of integration is recommended for Property Management Systems, Booking systems, etc.

Example flow:

1. You get a new reservation. Just gather all the relevant details.
2. Perform a member create API call. Remember to store the returned member_id in your database

POST https://api.akiles.app/v2/members
Content-Type: application/json;charset=UTF-8

{
  "name": "John Doe",
  "starts_at": "2018-03-13T16:56:51.766836837Z",
  "ends_at": "2018-03-13T16:56:51.766836837Z"
}

3. Based on the reservation or booking parameters, associate a group to the recently created member. The group will determine which set of spaces the guest will have access. Do a group association create API request.

POST https://api.akiles.app/v2/members/{member_id}/group_associations
Content-Type: application/json;charset=UTF-8

{
  "member_group_id": "mg_3merk33gt1692dk2p2m1"
}

4. Create an access method for the member. You can choose between:

• Email: the user gets an invitation email. They log in to the Akiles app with that email and get access.
• Magic link: you obtain a link with a unique code that grants access to the app, and send it to the user yourself (e.g. via e-mail, SMS, WhatsApp).
• PIN: Akiles generates a random PIN, you send it to the user yourself. The Akiles device unlocks when you type that PIN.
• Card: You associate an NFC card to the member, the Akiles device unlocks when you tap the card to it.

Email and magic link access methods allow opening via internet if the user chooses to open them in a web browser, or via internet, bluetooth and mobile NFC if the user chooses to install the native Android or iOS app.

You can use multiple access methods in a member at the same time, for example email+PIN+card. You can also use multiple of the same method. For example if a reservation is for two people you can associate two emails to the member, or two cards.

For example, for magic links, do a magic link create API request. The response contains the magic link.

POST https://api.akiles.app/v2/members/{member_id}/magic_links
Content-Type: application/json;charset=UTF-8

{}

As another example, to add a PIN use the PIN create request. The assigned PIN is returned in the response.

POST https://api.akiles.app/v2/members/{member_id}/pins
Content-Type: application/json;charset=UTF-8

{
  "length": 6
}

Whitelabel integration

For this kind of integration the user will directly interact with the gadgets, going through a custom experience. You will be responsible for implementing a proper UX/UI and or equivalent business logic.

As an example, the final user will typically login in your platform. You will have to implement all the permissions and conditions before granting the user access to the gadget. Finally, if theese conditions are met, your backend will call the gadget action endpoint in order to perform the action. You will prevously need to call gadget list endpoint in order to get the ids.

Example flow:

1. The end user logs in into your app or website
2. Your platform checks against your backend or database if the end user meets certain requirements before accessing the action button (have a valid reservation, plan, account, etc...)
3. The user clicks the action button. Your backend does the gadget action API call with the gadget id of the gadget related to the space you want the action to happen

POST https://api.akiles.app/v2/gadgets/{gadget_id}/actions/open
Content-Type: application/json;charset=UTF-8

{}

4. Handle response or error

OAuth authentication uses the standard RFC-6479 OAuth 2.0 protocol. It allows your app to interactively request access to customers' Akiles organizations and obtain access tokens for them. This makes the experience smoother and more secure, since the customer doesn't have to manually copy and paste a sensitive API key.

This section is not intended to be a full explanation on how OAuth works, just a quick reference to get started. For more info, consult online documentation about OAuth.

Client ID and Client Secret

Your OAuth application needs a Client ID and a Client Secret to operate.

• The Client ID is considered public, it is OK to expose it to frontends (and is in fact necessary to do so).
• The Client Secret must be maintained confidential since it is used to obtain access tokens. Always use it from your server, never send it or expose it to your frontend.

To obtain your application's Client ID and Secret, contact support@akiles.app.

Token types

• Access token: used to make API calls, expires 1 hour after issuance.
• Refresh token: used to obtain new access tokens when they expire.

Authorization flow

1. Generate a cryptographically-secure random string state and store it somewhere you can access it later (e.g. a cookie)
2. Start the flow by redirecting the user to the following URL:

https://auth.akiles.app/oauth2/auth?client_id=CLIENT_ID_HERE>&redirect_uri=https://your-app.example.com/redirect&response_type=code&scope=full_read_write offline&state=STATE_HERE

3. The Akiles authorization server will prompt the user to choose a user account and organization.
4. The Akiles authorization server will ask the user to authorize your requested scopes.
5. The user gets redirected to your redirect_uri:

https://your-app.example.com/redirect?code=CODE_HERE&scope=full_read_write offline&state=STATE_HERE

6. Check the state you have received matches the original state you stored. If it doesn't, abort. This is necessary to protect against CSRF / session poisoning attacks.
7. Exchange the authorization code for the access and refresh tokens.

POST https://auth.akiles.app/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
client_id=CLIENT_ID_HERE
client_secret=CLIENT_SECRET_HERE
code=CODE_HERE

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "ACCESS_TOKEN_HERE",
  "expires_in": 3599,
  "refresh_token": "REFRESH_TOKEN_HERE",
  "scope": "full_read_write offline",
  "token_type": "bearer"
}

8. You're done! Save the access token and refresh token.

You can now use the access token to make API calls on behalf of the user's organization. Just include an Authorization: Bearer header with the access token:

GET https://api.akiles.app/v2/organization
Authorization: Bearer ACCESS_TOKEN_HERE

The access token expires in 1 hour. You can obtain new access tokens with the refresh token.

Refresh token flow

POST https://auth.akiles.app/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
client_id=CLIENT_ID_HERE
client_secret=CLIENT_SECRET_HERE
refresh_token=REFRESH_TOKEN_HERE

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "NEW_ACCESS_TOKEN_HERE",
  "expires_in": 3599,
  "refresh_token": "NEW_REFRESH_TOKEN_HERE",
  "scope": "full_read_write offline",
  "token_type": "bearer"
}

Store both the new access and refresh tokens. The old refresh token, once used, is no longer guaranteed to keep working forever.

Scopes

• full_read_write: read-write access to all the objects. Same as an administrator user.
• full_read_only: read-only access to all the objects.
• offline: allows offline access. You need this to obtain refresh tokens.

Webhooks

Webhook objects are scoped to your OAuth application. That is, webhooks created manually from the admin panel won't be visible to you, and webhooks you create won't be visible in the admin panel.

All your application's webhooks in an organization will be deleted when your app gets deauthorized.

Even if you have read-only access, you can still create/edit/delete webhooks. This allows you to receive real-time updates in an application that only needs to read data from the Akiles organization.

The API uses cursor-based pagination. All list endpoints return data in reverse chronological order, and have the following common structure:

GET parameters

• limit: How many items to fetch, between 1 and 100
• cursor: Value of cursor_next from a previous request. If not given, it will fetch the most recent items.

Response data

• data: The received items, in a JSON array.
• has_next: Whether there are more items to fetch.
• cursor_next: Cursor to fetch the next page of items. Only present if has_next is true.

Most API objects allow you to attach your own, arbitrary key-value metadata in the metadata field. You can use it to store references to primary keys of your database, custom states, etc.

Metadata is visible to anyone with admin or API access to your organization. There is a storage limit of 1024 bytes of metadata per object.

Everything in Akiles APIs belongs to an Organization. An organization represents one Akiles customer and can handle multiple sites, gadgets, etc.. Access tokens are tied to organizations too, and they give access only to the objects belonging to the organization.

A site is a physical place where Akiles gadgets are installed. For example, it can be a building, a floor... Gadgets belong to a particular site.

End users will see one "card" in their app's home screen per site. The site information (email, contact, etc) is displayed in that card.

Physical Akiles device installed in the organization.

Each device has a set of capabilities which depend on the product.

The device object also contains an overview of the current device status (online/offline, battery level).

If hardware_id = null, the device is "virtual". It is designed for API testing: it behaves as close as possible to a real device in API calls but is not backed by a real hardware device. Gadget actions always succeed.

A gadget is a "thing that can be controlled" by the user. Gadgets can be doors, lights, heating, window blinds...

Gadgets are NOT physical devices. Some devices can have multiple gadgets because they have multiple inputs/outputs so they can control multiple things (Controllers). Others can have only one (the Cylinder and the Roomlock, for example). Others can have none (the Gateway Ethernet, for example.

Gadgets can have multiple actions depending on what they are. For example, a normal door will just have an open action, but a blind\ncan have raise and lower actions, and a light can have on and off actions. Actions are identified by their string ID, and they\nalso have a human-friendly name for display in the UI.

Everything that happens in an Akiles organization is logged as an Event.

Events are structured in "subject - verb - object" form:

• Subject: who did the action. It can be a member, an administrator, an OAuth application...
• Verb: what action was done on the object. Create, edit, delete, use...
• Object: what object the action was done on. A member, a gadget...

For example:

• gadget action events (i.e. someone opening a door) are reported with the member in the subject, use as verb, and the gadget action as object.
• Member editions are reported with the admin user who did the action in the subject, edit as the verb, and the member as the object.

Offline delayed events

Gadget action events originate from the Akiles device when the user uses PINs, NFC cards or phone, or BT from a phone to open. If the Akiles device is offline (i.e. has no connection to Akiles Cloud), it buffers events in local persistent memory and reports them later when it becomes online again. When this happens, the event appears with the created_at corresponding to the moment it originally happened, NOT the moment when it was reported.

Webhooks allow your server to receive real-time notifications about events happening in the Akiles organization.

Webhooks send a POST request to the indicated url when a matching event occurs. The request body is a JSON-encoded event, same as you would get in the response of the "get event" endpoint.

URL can be HTTP or HTTPS. We strongly recommend using HTTPS for production.

Filtering

Each webhook has a "filter" which specifies which events should be sent to it. A filter is a list of "filter rules". Each rule specifies:

• object_type: The value of object.type to match. This must be specified, i.e. it's NOT possible to subscribe to all object types.
• verb: The value of verb to match. If it's set to null it matches all verbs, i.e. it IS possible to subscribe to all events about one object type, all verbs.

The webhook filter matches if any of the rules in the array match.

Some examples:

• "filter": []: Matches no events. Events match if at least one filter rule matches, which can't happen if there's no rules at all.
• "filter": [{"verb": "use", "object_type": "gadget_action"}]: Matches gadget action events.
• "filter": [{"object_type": "member"}]: Matches all events related to members (creation, edition, deletion...)
• "filter": [{"verb": "edit", "object_type": "member"}]: Matches member edition events.
• "filter": [{"verb": "edit", "object_type": "member"}, {"verb": "use", "object_type": "gadget_action"}]: Matches member editions, and gadget actions.

An event will be sent to this webhook if it matches at least one rule. If it matches multiple rules, it will only be sent once. If it matches multiple webhook objects, it will be sent once per webhook to its respective URL, even if the URL is the same.

Signature

If an attacker learns the URL of your webhook, they could send requests themselves to it, spoofing webhooks. To prevent this, Akiles signs the webhook requests so that your server can check they come from Akiles and not an attacker. It's strongly recommended to verify the signature.

The signature is the result of applying HMAC-SHA256 to the raw request body bytes, using the webhook secret as a key. It's sent in the X-Akiles-Sig-SHA256 HTTP header.

The secret is returned when you create the webhook. It's not possible to view the secret of an existing webhook, you have to delete and recreate it instead.

The following is an example of how to receive webhooks and validate the signature using nodejs:

import url from 'url'
import http from 'http'
import crypto from 'crypto'

// replace with the secret you get when creating the webhook.
const webhookSecret = 'f305d484fd10de285b00bb203659e863';

const app = http.createServer((request, response) => {
    let body = [];
    request.on('data', (chunk) => {
        body.push(chunk);
    }).on('end', () => {
        body = Buffer.concat(body).toString();

        const gotSig = Buffer.from(request.headers['x-akiles-sig-sha256'], 'hex');
        const expectedSig = crypto.createHmac("sha256", webhookSecret).update(body).digest();
        const ok = crypto.timingSafeEqual(gotSig, expectedSig);
        if (!ok) {
            response.writeHead(400);
            response.write('bad sig');
            response.end();
            return;
        }

        const event = JSON.parse(body.toString());
        console.log('Got event!');
        console.log(event);

        response.writeHead(200);
        response.write('cool');
        response.end();
    });
});

app.listen(8088);

Delivery

Webhook delivery is considered successful if your server returns a 2xx status code.

Unsuccessful deliveries are retried, with an exponential backoff starting at a few seconds and doubling every time, for up to 1 hour.