SDK

The Akiles SDK allows your Android or iOS app to interact with Akiles devices. It integrates all communication methods supported by Akiles devices (Internet, Bluetooth, NFC) to ensure maximum reliability and a great user experience.

It is the recommended solution to allow your users to open doors from your own app, since it works even if either the phone or the Akiles device (or both!) are offline.

Akiles’s own app uses the SDK :)

Features

Stores session data locally (device and gadget list, private keys) to allow offline operation.
Executes gadget actions (e.g. open, lock, unlock a door) via:
- Internet
- Bluetooth
- NFC card emulation (HCE)
Integrates with the member permission system.
Handles geolocation check automatically if required by the member’s permissions.
Scan for nearby Akiles devices.
Update the configuration database of Akiles devices via Bluetooth.
Scan Akiles and non-Akiles NFC cards.
Update the data stored in Akiles NFC cards.

Platforms

The SDK supports all major mobile platforms.

React Native wrapper over the native SDKs

Cordova

Cordova wrapper over the native SDKs

Usage

Setup

The SDK works together with the Akiles API and the member permission system.

From your server, create a member and assign it to one or more groups. This defines the permissions of the member, i.e. what doors can they access. See here for more information on the permission system.

Next, from your server, create a member token for this member. This is a special kind of token that grants access only to the actions the member has permission to do. The SDK uses this token to communicate with Akiles devices and servers.

Send the token from your server to your app, and add it to the SDK by calling addSession(). The SDK then downloads session data and stores it locally in the phone. This is the last step that requires an internet connection. Once this is done, the SDK is ready to use, even offline.

Warning

NEVER send the main Akiles API credentials (client secret, access/refresh tokens) to the app. They grant access to everything in the organization. ONLY send member tokens to the app.

    sequenceDiagram
    participant Akiles API
    participant Your server
    participant Your app
    participant Akiles SDK
    Your server->>Akiles API: Create member
    Your server->>Akiles API: Create member group association
    Your server->>Akiles API: Create member token
    Akiles API-->>Your server: Member token
    Your server->>Your app: Member token
    Your app->>Akiles SDK: addSession(Member token)
    Akiles SDK->>Akiles API: Get session data
    Akiles API-->>Akiles SDK: Session data
    Akiles SDK->>Akiles SDK: Store session data in local storage

Refresh session

The SDK stores some data about the session in the phone’s local storage to ensure it can work offline. This data needs to be refreshed periodically to ensure it’s up to date. Examples of cases where refresh is needed:

The member’s permissions have been changed.
A device has been physically replaced (this keeps the gadget ID the same, but the hardware ID changes and the SDK needs to know)

We recommend you refresh often, for example every time the user opens the app or enters the screen where they can do the gadget actions. To refresh, call refreshSession():

    sequenceDiagram
    participant Akiles API
    participant Your app
    participant Akiles SDK
    Your app->>Akiles SDK: refreshSession(Member token)
    Akiles SDK->>Akiles API: Get session data
    Akiles API-->>Akiles SDK: Session data
    Akiles SDK->>Akiles SDK: Update session data in local storage
    Your app->>Akiles SDK: getGadgets()
    Akiles SDK-->>Your app: Gadget list
    Your app->>Your app: Display gadgets on screen

refreshSession() requires a working internet connection. If there’s no connection it will return an error, but the data from the last refresh is still available. It is important you handle this case gracefully and still allow the user to do gadget actions. You should show the gadget list anyway and not block user interaction with fullscreen error messages. Otherwise, the user won’t be able to open doors without internet access, which is the whole reason the SDK exists!

    sequenceDiagram
    participant Akiles API
    participant Your app
    participant Akiles SDK
    Your app->>Akiles SDK: refreshSession(Member token)
    Akiles SDK-xAkiles API: Get session data
    note over Akiles API: No internet!
    Akiles SDK-->>Your app: INTERNET_NOT_AVAILABLE
    Your app->>Akiles SDK: getGadgets()
    Akiles SDK-->>Your app: Old gadget list
    Your app->>Your app: Display gadgets on screen

Action!

To do an action, call action().

The SDK tries doing it via internet and via Bluetooth in parallel. When one communication method succeds, the other is canceled.

    sequenceDiagram
    participant Akiles API
    participant Your app
    participant Akiles SDK
    Your app->>Akiles SDK: action()
    Akiles SDK-->>Akiles API: Do action via internet
    Akiles SDK-->>Akiles device: Do action via Bluetooth
    Akiles SDK-->>Your app: Action result callbacks

Permissions

The SDK handles requesting location and Bluetooth permissions automatically if needed. In case the user denies the permissions, handle it the following way:

If you get a *_PERMISSION_NOT_GRANTED error: Explain to the user why the permission is needed, and offer to try again.
If you get a *_PERMISSION_NOT_GRANTED_PERMANENTLY error: requesting the permission is no longer possible because the user denied the permission twice (Android 11+) or checked the “Don’t ask again” box (Android 10 or lower). Explain to the user why the permission is denied, and take the user to the “App info” screen so they can grant the permission manually.

If you prefer the SDK to not automatically request permissions you can set requestLocationPermission, requestBluetoothPermission to false in ActionOptions. This will cause it to immediately error with *_PERMISSION_NOT_GRANTED instead of requesting the permission. You can then show your own UI explaining why the permission is needed, and retry with true if the user chooses to go ahead.

Card emulation

The SDK can do NFC card emulation to allow opening doors via holding it in front of an NFC-enabled Akiles device. Check out the guide for Android and iOS for how to configure it.

Security

Follow the recommendations below to ensure the security of your integration.

Akiles API credentials

Never send the main Akiles API credentials (client secret, access/refresh tokens) to the app. They grant access to everything. You should only send member tokens to the app.

Use TLS

Use Transport Layer Security (TLS) when sending the member token from your server to your app, to prevent network attackers from obtaining it.

(The Akiles SDK already uses TLS for its own communication with the Akiles servers.)

One member per user

We strongly recommend you create a different member for each user in your system. This has a few advantages:

The members’s name shows up in the “Logs” screen in the Akiles admin panel. This allows administrators to get detailed information on who opened which door at which time, for audit purposes.
You can easily assign different permissions to different members, or change the permissions of one member after it has been created.

One token per session

We also recommend you create a new member token for each session, i.e. every time a user logs in to a different device, and delete the member token when the user logs out or when you delete the session due to inactivity.

Using the same member token for all sessions is a security risk: if the user logs into an untrusted device where an attacker can obtain the member token, the attacker will get permanent access to the user’s permissions. If you create one token per device, the attacker loses access when the user logs out.
The Event object contains which member token did an action, so you can learn from which device an action was performed for audit purposes.