Akiles API Reference
Akiles API
API Endpoint
https://api.akiles.app/v2Version: 2.0
Metadata
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.
metadata
Key-value metadata
Example
{
"key1": "value1",
"key2": "value2"
}
Organizations
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.
organization
|
id
string (organization_id) |
Unique identifier. |
|
name
string |
Name. |
|
is_deleted
boolean |
Indicates if the object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "org_3merk33gt1v9ypgfzrp1",
"name": "SkyCowork",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get organization
Response Example (200 OK)
{
"id": "org_3merk33gt1v9ypgfzrp1",
"name": "SkyCowork",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit organization
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "org_3merk33gt1v9ypgfzrp1",
"name": "SkyCowork",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Sites
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.
location
|
lat
number (float) |
Latitude in degrees |
|
lng
number (float) |
Longitude |
Example
{
"lat": 41.290485,
"lng": 2.1829076
}
site_geo
|
location
location |
|
|
radius
number |
Radius in meters |
Example
{
"location": {
"lat": 41.290485,
"lng": 2.1829076
},
"radius": 100
}
site_map
|
location
location |
|
|
place_id
string |
place_id from Google Maps Places API |
|
address
string |
Human-readable address |
|
image_url
string |
Map image URL, displayed in the site's header in the app. |
Example
{
"location": {
"lat": 41.290485,
"lng": 2.1829076
},
"place_id": "string",
"address": "string",
"image_url": "string"
}
site
|
id
string (site_id) |
site ID |
|
name
string |
Site name |
|
organization_id
string (organization_id) |
organization ID |
|
geo
site_geo |
|
|
map
site_map |
|
|
phone
string |
Phone number. Shown in the site info in the app. |
|
email
string |
Email. Shown in the site info in the app. |
|
info
string |
Free-form extra information. Shown in the site info in the app. |
|
timezone
string (timezone) |
Local time zone of the site. |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "site_3merk33gt21kym11een1",
"name": "string",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"geo": {
"location": {
"lat": 41.290485,
"lng": 2.1829076
},
"radius": 100
},
"map": {
"location": {
"lat": 41.290485,
"lng": 2.1829076
},
"place_id": "string",
"address": "string",
"image_url": "string"
},
"phone": "string",
"email": "string",
"info": "string",
"timezone": "Europe/Madrid",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List sites
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
|
data
site |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "site_3merk33gt21kym11een1",
"name": "string",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"geo": {
"location": {
"lat": 41.290485,
"lng": 2.1829076
},
"radius": 100
},
"map": {
"location": {
"lat": 41.290485,
"lng": 2.1829076
},
"place_id": "string",
"address": "string",
"image_url": "string"
},
"phone": "string",
"email": "string",
"info": "string",
"timezone": "Europe/Madrid",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Get site
site ID
Response Example (200 OK)
{
"id": "site_3merk33gt21kym11een1",
"name": "string",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"geo": {
"location": {
"lat": 41.290485,
"lng": 2.1829076
},
"radius": 100
},
"map": {
"location": {
"lat": 41.290485,
"lng": 2.1829076
},
"place_id": "string",
"address": "string",
"image_url": "string"
},
"phone": "string",
"email": "string",
"info": "string",
"timezone": "Europe/Madrid",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit site
site ID
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "site_3merk33gt21kym11een1",
"name": "string",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"geo": {
"location": {
"lat": 41.290485,
"lng": 2.1829076
},
"radius": 100
},
"map": {
"location": {
"lat": 41.290485,
"lng": 2.1829076
},
"place_id": "string",
"address": "string",
"image_url": "string"
},
"phone": "string",
"email": "string",
"info": "string",
"timezone": "Europe/Madrid",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Products
product
|
id
string |
product ID |
|
name
string |
Human-friendly product name. Show this to the user instead of the product ID! |
Example
{
"id": "controller_ethernet",
"name": "Controller Ethernet"
}
List products
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
|
data
product |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "controller_ethernet",
"name": "Controller Ethernet"
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Get product
product ID
Response Example (200 OK)
{
"id": "controller_ethernet",
"name": "Controller Ethernet"
}
Devices
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.
device
|
id
string (device_id) |
device ID |
|
created_at
string (date-time) |
Creation time for this object. |
|
name
string |
Device name |
|
organization_id
string (organization_id) |
organization ID |
|
site_id
string (site_id) |
site ID |
|
hardware_id
string (hardware_id) |
Hardware ID. This is the serial number printed in the device's label, as a QR and in some products as text. |
|
metadata
metadata |
Key-value metadata |
|
product_id
string |
Product ID. NOTE: do not show this to the user directly, it's not capitalized properly. Use the |
|
revision_id
string |
Hardware revision ID. |
|
input_rules
device_input_rule |
Input rule array. Input rules configure a device to remotely trigger gadget actions on other devices remotely when the user inputs a PIN or an NFC card. Must be empty if |
|
capabilities
device_capabilities |
Device capabilities. |
|
status
device_status |
Device status. |
|
is_deleted
boolean |
True if this object has been deleted. |
Example
{
"id": "dev_3merk33gt3l525ryhcmh",
"created_at": "2024-03-13T16:56:51.766836837Z",
"name": "string",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"hardware_id": "hw_3merk33gt2a7grgmljhh",
"metadata": {
"key1": "value1",
"key2": "value2"
},
"product_id": "controller_ethernet",
"revision_id": "06",
"input_rules": [
{
"code": "*2",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "open"
}
],
"capabilities": {
"gadgets": "multiple",
"gadget_max_count": 6,
"script": true,
"internet": true,
"ethernet": true,
"wifi": false,
"cellular": false,
"pin": false,
"nfc": false,
"input_rules": false,
"mains": true,
"battery": true,
"battery_rechargeable": true,
"audio": true
},
"status": {
"online": true,
"mains_present": true,
"battery_present": true,
"battery_charging": true,
"battery_percent": 87.2
},
"is_deleted": false
}
device_capabilities
Device capabilities.
|
gadgets
string none, single, multiple |
What level of gadget support this device has. |
|
gadget_max_count
integer |
Maximum amount of gadgets the device supports. Will always be |
|
script
boolean |
Whether this device supports gadgets with custom scripts. |
|
internet
boolean |
Whether this device supports some form of internet connection, which means it can connect to Akiles Cloud directly instead of through gateways. |
|
ethernet
boolean |
Whether this device supports Ethernet. |
|
wifi
boolean |
Whether this device supports WiFi. |
|
cellular
boolean |
Whether this device supports cellular internet. |
|
pin
boolean |
Whether this device supports PIN entry (i.e. has a keypad). |
|
nfc
boolean |
Whether this device supports NFC (either physical cards, or emulated cards in a phone) |
|
input_rules
boolean |
Whether this device supports input rules. |
|
mains
boolean |
Whether this device supports being powered from mains (either directly or with an AC adapter). |
|
battery
boolean |
Whether this device supports being powered by batteries (rechargeable or not). It is possible for both |
|
battery_rechargeable
boolean |
If true, this device contains a rechargeable battery, and can recharge it from mains power. |
|
audio
boolean |
If true, this device is equipped with a buzzer capable of emitting sounds for interactions and status updates. |
Example
{
"gadgets": "multiple",
"gadget_max_count": 6,
"script": true,
"internet": true,
"ethernet": true,
"wifi": false,
"cellular": false,
"pin": false,
"nfc": false,
"input_rules": false,
"mains": true,
"battery": true,
"battery_rechargeable": true,
"audio": true
}
device_status
Device status.
|
online
boolean |
True if this device is online (meaning it's on and has a working connection to Akiles Cloud, either directly or through gateways). |
|
mains_present
boolean |
True if this device currently has mains power. |
|
battery_present
boolean |
True if this device currently has a battery inserted. |
|
battery_charging
boolean |
True if this device currently is charging the battery from mains power. |
|
battery_percent
number |
Battery percentage, 0-100. |
Example
{
"online": true,
"mains_present": true,
"battery_present": true,
"battery_charging": true,
"battery_percent": 87.2
}
device_input_rule
Input rules allow configuring "codes" that act as prefixes for PINs or cards. This allows a single device to
- Trigger different gadgets (local or remote).
- Trigger different actions in a gadget.
- Mix local and remote gadgets. One input rule can point to a local gadget (in this device), and another to a remote gadget (in another device, will be triggered via AkilesNet).
Example:
"input_rules": [
{
"code": "1",
"gadget_id": "gad_3z4f8pubhdcj2fvfmkxh", // street
"action_id": "open"
},
{
"code": "2",
"gadget_id": "gad_3z4f8s623va4l9nea7u1", // garage door
"action_id": "up"
},
{
"code": "3",
"gadget_id": "gad_3z4f8s623va4l9nea7u1", // garage door
"action_id": "down"
},
{
"code": "4",
"gadget_id": "gad_3z4f8s623va4l9nea7u1", // garage door
"action_id": "stop"
}
]
Typing "1" and your PIN, or typing "1" and tapping your card/phone would open the street door. Same with "2" would move the garage door up, "3" down, etc.
Keypad rule codes accept digits 0-9, hash # and star *.
You can define one keypad rule as the "default" one by setting the code to "". This is the rule that will be triggered if you type a PIN or tap a card directly without typing anything before. A default rule can coexist with other rules at the same time, but then all the other rules can't start with a digit (only with * or #), because it'd otherwise be ambiguous whether the user is typing a rule code or a PIN.
If no input rules are defined (input_rules is an empty array), pins/cards will open the first action of the first gadget in the current device.
|
code
string |
Keypad code prefix. String consisting of digits 0-9, pound ( |
|
gadget_id
string (gadget_id) |
Destination gadget ID. It can be a gadget on this device, or on another device. |
|
action_id
string |
Destination action ID. It must be a valid action in the destination gadget. |
Example
{
"code": "*2",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "open"
}
List devices
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
|
data
device |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "dev_3merk33gt3l525ryhcmh",
"created_at": "2024-03-13T16:56:51.766836837Z",
"name": "string",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"hardware_id": "hw_3merk33gt2a7grgmljhh",
"metadata": {
"key1": "value1",
"key2": "value2"
},
"product_id": "controller_ethernet",
"revision_id": "06",
"input_rules": [
{
"code": "*2",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "open"
}
],
"capabilities": {
"gadgets": "multiple",
"gadget_max_count": 6,
"script": true,
"internet": true,
"ethernet": true,
"wifi": false,
"cellular": false,
"pin": false,
"nfc": false,
"input_rules": false,
"mains": true,
"battery": true,
"battery_rechargeable": true,
"audio": true
},
"status": {
"online": true,
"mains_present": true,
"battery_present": true,
"battery_charging": true,
"battery_percent": 87.2
},
"is_deleted": false
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Get device
device ID
Response Example (200 OK)
{
"id": "dev_3merk33gt3l525ryhcmh",
"created_at": "2024-03-13T16:56:51.766836837Z",
"name": "string",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"hardware_id": "hw_3merk33gt2a7grgmljhh",
"metadata": {
"key1": "value1",
"key2": "value2"
},
"product_id": "controller_ethernet",
"revision_id": "06",
"input_rules": [
{
"code": "*2",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "open"
}
],
"capabilities": {
"gadgets": "multiple",
"gadget_max_count": 6,
"script": true,
"internet": true,
"ethernet": true,
"wifi": false,
"cellular": false,
"pin": false,
"nfc": false,
"input_rules": false,
"mains": true,
"battery": true,
"battery_rechargeable": true,
"audio": true
},
"status": {
"online": true,
"mains_present": true,
"battery_present": true,
"battery_charging": true,
"battery_percent": 87.2
},
"is_deleted": false
}
Edit device
device ID
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "dev_3merk33gt3l525ryhcmh",
"created_at": "2024-03-13T16:56:51.766836837Z",
"name": "string",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"hardware_id": "hw_3merk33gt2a7grgmljhh",
"metadata": {
"key1": "value1",
"key2": "value2"
},
"product_id": "controller_ethernet",
"revision_id": "06",
"input_rules": [
{
"code": "*2",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "open"
}
],
"capabilities": {
"gadgets": "multiple",
"gadget_max_count": 6,
"script": true,
"internet": true,
"ethernet": true,
"wifi": false,
"cellular": false,
"pin": false,
"nfc": false,
"input_rules": false,
"mains": true,
"battery": true,
"battery_rechargeable": true,
"audio": true
},
"status": {
"online": true,
"mains_present": true,
"battery_present": true,
"battery_charging": true,
"battery_percent": 87.2
},
"is_deleted": false
}
Gadgets
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.
gadget_action
|
id
string |
action ID |
|
name
string |
Action user-friendly name |
Example
{
"id": "open",
"name": "Open"
}
gadget
|
id
string (gadget_id) |
gadget ID |
|
organization_id
string (organization_id) |
organization ID |
|
site_id
string (site_id) |
site ID |
|
device_id
string (device_id) |
device ID |
|
name
string |
Gadget name |
|
actions
gadget_action |
|
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "gad_3merk33gt1hnl6pvbu71",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"device_id": "dev_3merk33gt3l525ryhcmh",
"name": "string",
"actions": [
{
"id": "open",
"name": "Open"
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List gadgets
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
|
data
gadget |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "gad_3merk33gt1hnl6pvbu71",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"device_id": "dev_3merk33gt3l525ryhcmh",
"name": "string",
"actions": [
{
"id": "open",
"name": "Open"
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Get gadget
gadget ID
Response Example (200 OK)
{
"id": "gad_3merk33gt1hnl6pvbu71",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"device_id": "dev_3merk33gt3l525ryhcmh",
"name": "string",
"actions": [
{
"id": "open",
"name": "Open"
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit gadget
gadget ID
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "gad_3merk33gt1hnl6pvbu71",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"device_id": "dev_3merk33gt3l525ryhcmh",
"name": "string",
"actions": [
{
"id": "open",
"name": "Open"
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Do gadget action
This endpoint is only available to Akiles customers that have the whitelabel integration feature which has extra cost. If you want to make your integration public we recommend using the non whitelabel option.
gadget ID
gadget action ID
Request Example
{}
Response Example (200 OK)
{}
Members
member
|
id
string (member_id) |
member ID |
|
organization_id
string (organization_id) |
organization ID |
|
name
string |
Member name shown in the admin panel. This is for the organization admins to identify the member, it's never shown to the user. |
|
starts_at
string (date-time) |
Start date of the member's access. If null, the access is valid immediately. |
|
ends_at
string (date-time) |
End date of the member's access. If null, the access is valid forever (ie, until an end date is set or the member is deleted.) |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "mem_3merk33gt7ml3tde71f3",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "John Doe",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
member_email
|
id
string (member_email_id) |
member email ID |
|
organization_id
string (organization_id) |
organization ID |
|
member_id
string (member_id) |
member ID |
|
email
string (email_address) |
Email address |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "me_3rkd7ya2pnjysjqbluj1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"email": "hello@example.com",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
member_magic_link
|
id
string (member_magic_link_id) |
member magic link ID |
|
organization_id
string (organization_id) |
organization ID |
|
member_id
string (member_id) |
member ID |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "mml_3rkd2f2mv925ptvpgblh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
member_magic_link_revealed
|
link
string (url) |
Magic link for this member. The guest will be able to use Akiles instantly by clicking it. |
|
id
string (member_magic_link_id) |
member magic link ID |
|
organization_id
string (organization_id) |
organization ID |
|
member_id
string (member_id) |
member ID |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"link": "https://link.akiles.app/#ml_8502850982345_f00i1nslz20gkm",
"id": "mml_3rkd2f2mv925ptvpgblh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
member_pin
|
id
string (member_pin_id) |
member pin ID |
|
organization_id
string (organization_id) |
organization ID |
|
member_id
string (member_id) |
member ID |
|
length
integer |
Pin length |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "mp_3rkd2fmgmmdh1dgkvluh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"length": 6,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
member_pin_revealed
|
pin
string |
Pin number. |
|
id
string (member_pin_id) |
member pin ID |
|
organization_id
string (organization_id) |
organization ID |
|
member_id
string (member_id) |
member ID |
|
length
integer |
Pin length |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"pin": "123456",
"id": "mp_3rkd2fmgmmdh1dgkvluh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"length": 6,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
member_card
|
id
string (member_card_id) |
member card ID |
|
organization_id
string (organization_id) |
organization ID |
|
member_id
string (member_id) |
member ID |
|
card_id
string (card_id) |
card ID |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "mc_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"card_id": "crd_3ykdnnld7d57x83eqcm1",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
member_token
|
id
string (member_token_id) |
member token ID |
|
organization_id
string (organization_id) |
organization ID |
|
member_id
string (member_id) |
member ID |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
member_token_revealed
|
token
string |
The token. |
|
id
string (member_token_id) |
member token ID |
|
organization_id
string (organization_id) |
organization ID |
|
member_id
string (member_id) |
member ID |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"token": "mt_3yd55tbrelfxhjjvkdqh_e39adeac25cdbd99c757124d70acb8b028bb471d8a2eebbc",
"id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
member_group_association
|
id
string (member_group_association_id) |
member group association ID |
|
organization_id
string (organization_id) |
organization ID |
|
member_id
string (member_id) |
member ID |
|
member_group_id
string (member_group_id) |
member_group ID |
|
starts_at
string (date-time) |
Start date of the member's access. If null, the access is valid immediately. |
|
ends_at
string (date-time) |
End date of the member's access. If null, the access is valid forever (ie, until an end date is set or the member is deleted.) |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "mga_3rkd81x2hc3qluv56pl1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List members
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
Filter by deletion status
Filter by email address
Filter by metadata.source
Filter by metadata.sourceID
|
data
member |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "mem_3merk33gt7ml3tde71f3",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "John Doe",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create member
|
name
string |
Member name shown in the admin panel. This is for the organization admins to identify the member, it's never shown to the user. |
|
starts_at
string (date-time) |
Start date of the member's access. If null, the access is valid immediately. |
|
ends_at
string (date-time) |
End date of the member's access. If null, the access is valid forever (ie, until an end date is set or the member is deleted.) |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"name": "John Doe",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mem_3merk33gt7ml3tde71f3",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "John Doe",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get member
member ID
Response Example (200 OK)
{
"id": "mem_3merk33gt7ml3tde71f3",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "John Doe",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit member
member ID
|
name
string |
Member name shown in the admin panel. This is for the organization admins to identify the member, it's never shown to the user. |
|
starts_at
string (date-time) |
Start date of the member's access. If null, the access is valid immediately. |
|
ends_at
string (date-time) |
End date of the member's access. If null, the access is valid forever (ie, until an end date is set or the member is deleted.) |
|
is_deleted
boolean |
True if this object has been deleted. |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"name": "John Doe",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mem_3merk33gt7ml3tde71f3",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "John Doe",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Delete member
member ID
Response Example (200 OK)
{
"id": "mem_3merk33gt7ml3tde71f3",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "John Doe",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List emails
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Search parameter
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
member ID
|
data
member_email |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "me_3rkd7ya2pnjysjqbluj1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"email": "hello@example.com",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create email
member ID
|
email
string (email) |
Email address |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"email": "string (email)",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "me_3rkd7ya2pnjysjqbluj1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"email": "hello@example.com",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get email
member ID
member email ID
Response Example (200 OK)
{
"id": "me_3rkd7ya2pnjysjqbluj1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"email": "hello@example.com",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit email
member ID
member email ID
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "me_3rkd7ya2pnjysjqbluj1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"email": "hello@example.com",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Delete email
member ID
member email ID
Response Example (200 OK)
{
"id": "me_3rkd7ya2pnjysjqbluj1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"email": "hello@example.com",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List magic links
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
member ID
|
data
member_magic_link |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "mml_3rkd2f2mv925ptvpgblh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create magic link
member ID
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"link": "https://link.akiles.app/#ml_8502850982345_f00i1nslz20gkm",
"id": "mml_3rkd2f2mv925ptvpgblh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get magic link
member ID
member magic link ID
Response Example (200 OK)
{
"id": "mml_3rkd2f2mv925ptvpgblh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit magic link
member ID
member magic link ID
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mml_3rkd2f2mv925ptvpgblh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Delete magic link
member ID
member magic link ID
Response Example (200 OK)
{
"id": "mml_3rkd2f2mv925ptvpgblh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Reveal magic link
member ID
member magic link ID
Request Example
{}
Response Example (200 OK)
{
"link": "https://link.akiles.app/#ml_8502850982345_f00i1nslz20gkm",
"id": "mml_3rkd2f2mv925ptvpgblh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List pins
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
member ID
|
data
member_pin |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "mp_3rkd2fmgmmdh1dgkvluh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"length": 6,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create pin
When creating a PIN, you can specify it in 3 ways depending on the fields you send in the request:
- No fields: Akiles generates a random PIN, of the length configured in the organization's settings.
lengthonly: Akiles generates a random PIN of the length you specify.pinonly: The PIN is the one you specify.
The generated random PIN is included in the response.
It is not allowed to have two (non-deleted) members with the same PIN in a given organization. For this reason, we recommend you let Akiles generate a random PIN instead of generating one yourself if you can (Akiles generates a PIN that is different to all existing members). If you specify the PIN directly, you have to ensure there's no PIN collisions yourself.
member ID
|
length
integer |
Pin length. Optional (you can either not specify it, or set it to |
|
pin
string |
Pin number. Optional (you can either not specify it, or set it to |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"length": 6,
"pin": "123456",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"pin": "123456",
"id": "mp_3rkd2fmgmmdh1dgkvluh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"length": 6,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get pin
member ID
member pin ID
Response Example (200 OK)
{
"id": "mp_3rkd2fmgmmdh1dgkvluh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"length": 6,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit pin
NOTE: It is not possible to edit a MemberPin to change a PIN. Instead, delete it and create a new one.
member ID
member pin ID
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mp_3rkd2fmgmmdh1dgkvluh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"length": 6,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Delete pin
member ID
member pin ID
Response Example (200 OK)
{
"id": "mp_3rkd2fmgmmdh1dgkvluh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"length": 6,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Reveal pin
member ID
member pin ID
Request Example
{}
Response Example (200 OK)
{
"pin": "123456",
"id": "mp_3rkd2fmgmmdh1dgkvluh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"length": 6,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List cards
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
member ID
|
data
member_card |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "mc_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"card_id": "crd_3ykdnnld7d57x83eqcm1",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create card
member ID
|
card_id
string (card_id) |
Card ID. Optional. One of |
|
printed_code
string |
Unique code physically printed on the card. Optional. One of |
|
uid
string |
ISO14443 UID for the card. Always 4, 7 or 10 bytes, encoded in hex. Optional. One of |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"card_id": "crd_3ykdnnld7d57x83eqcm1",
"printed_code": "WHJSA",
"uid": "041E53F2FF6780",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mc_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"card_id": "crd_3ykdnnld7d57x83eqcm1",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get card
member ID
member card ID
Response Example (200 OK)
{
"id": "mc_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"card_id": "crd_3ykdnnld7d57x83eqcm1",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit card
member ID
member card ID
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mc_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"card_id": "crd_3ykdnnld7d57x83eqcm1",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Delete card
member ID
member card ID
Response Example (200 OK)
{
"id": "mc_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"card_id": "crd_3ykdnnld7d57x83eqcm1",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List tokens
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
member ID
|
data
member_token |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create token
member ID
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"token": "mt_3yd55tbrelfxhjjvkdqh_e39adeac25cdbd99c757124d70acb8b028bb471d8a2eebbc",
"id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get token
member ID
member token ID
Response Example (200 OK)
{
"id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit token
member ID
member token ID
|
metadata
metadata |
Key-value metadata |
Request Example
{
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Delete token
member ID
member token ID
Response Example (200 OK)
{
"id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Reveal token
member ID
member token ID
Request Example
{}
Response Example (200 OK)
{
"token": "mt_3yd55tbrelfxhjjvkdqh_e39adeac25cdbd99c757124d70acb8b028bb471d8a2eebbc",
"id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List group associations
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
member ID
|
data
member_group_association |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "mga_3rkd81x2hc3qluv56pl1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create group association
member ID
|
member_group_id
string (member_group_id) |
member_group ID |
|
starts_at
string (date-time) |
Start date of the member's access. If null, the access is valid immediately. |
|
ends_at
string (date-time) |
End date of the member's access. If null, the access is valid forever (ie, until an end date is set or the member is deleted.) |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mga_3rkd81x2hc3qluv56pl1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get group association
member ID
member group association ID
Response Example (200 OK)
{
"id": "mga_3rkd81x2hc3qluv56pl1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit group association
member ID
member group association ID
|
starts_at
string (date-time) |
Start date of the member's access. If null, the access is valid immediately. |
|
ends_at
string (date-time) |
End date of the member's access. If null, the access is valid forever (ie, until an end date is set or the member is deleted.) |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mga_3rkd81x2hc3qluv56pl1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Delete group association
member ID
member group association ID
Response Example (200 OK)
{
"id": "mga_3rkd81x2hc3qluv56pl1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"starts_at": "2024-03-13T16:56:51.766836837Z",
"ends_at": "2024-03-13T16:56:51.766836837Z",
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Member groups
member_group
|
id
string (member_group_id) |
member_group ID |
|
organization_id
string (organization_id) |
organization ID |
|
name
string |
Group name |
|
permissions
member_group_permission_rule |
Permission rules granted to members of this group. A member can have multiple groups, and the permissions are the union of all the groups. Access is granted if at least one rule matches. |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "mg_3merk33gt1692dk2p2m1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "string",
"permissions": [
{
"site_id": "site_3merk33gt21kym11een1",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "string",
"schedule_id": "sch_3merk33gt21kyz1f3z1",
"presence": "string",
"access_methods": {
"online": "boolean",
"bluetooth": "boolean",
"mobile_nfc": "boolean",
"pin": "boolean",
"card": "boolean"
}
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
member_group_permission_rule
Rule granting permissions to a member group. Examples:
{}matches all gadgets in all sites{"site_id": "site_3merk33gt21kym11een1"}matches all gadgets in that site.{"gadget_id": "gad_3merk33gt1hnl6pvbu71"}matches that gadget only.
It is not allowed to set site_id and gadget_id at the same time.
|
site_id
string (site_id) |
Site ID. If set, the rule only matches gadgets in this site. |
|
gadget_id
string (gadget_id) |
Gadget ID. If set, the rule only matches this gadget. |
|
action_id
string |
Action ID. If set, the rule only matches this particular action within the gadget. Only one action can be chosen. If you want to allow multiple actions in the same gadget, create one permission rule for each action. If you set this, |
|
schedule_id
string (schedule_id) |
Schedule ID. If set, the rule only matches if the current time is within the schedule. |
|
presence
string none, gps |
Presence check performed.
Actions via PINs, cards and Bluetooth are always allowed and not affected by this setting. |
|
access_methods
object |
Allowed access methods.
|
Example
{
"site_id": "site_3merk33gt21kym11een1",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "string",
"schedule_id": "sch_3merk33gt21kyz1f3z1",
"presence": "string",
"access_methods": {
"online": "boolean",
"bluetooth": "boolean",
"mobile_nfc": "boolean",
"pin": "boolean",
"card": "boolean"
}
}
List member groups
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Search parameter
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
|
data
member_group |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "mg_3merk33gt1692dk2p2m1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "string",
"permissions": [
{
"site_id": "site_3merk33gt21kym11een1",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "string",
"schedule_id": "sch_3merk33gt21kyz1f3z1",
"presence": "string",
"access_methods": {
"online": "boolean",
"bluetooth": "boolean",
"mobile_nfc": "boolean",
"pin": "boolean",
"card": "boolean"
}
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create member group
|
name
string |
Group name |
|
permissions
member_group_permission_rule |
Permission rules granted to members of this group. A member can have multiple groups, and the permissions are the union of all the groups. Access is granted if at least one rule matches. |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"name": "string",
"permissions": [
{
"site_id": "site_3merk33gt21kym11een1",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "string",
"schedule_id": "sch_3merk33gt21kyz1f3z1",
"presence": "string",
"access_methods": {
"online": "boolean",
"bluetooth": "boolean",
"mobile_nfc": "boolean",
"pin": "boolean",
"card": "boolean"
}
}
],
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mg_3merk33gt1692dk2p2m1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "string",
"permissions": [
{
"site_id": "site_3merk33gt21kym11een1",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "string",
"schedule_id": "sch_3merk33gt21kyz1f3z1",
"presence": "string",
"access_methods": {
"online": "boolean",
"bluetooth": "boolean",
"mobile_nfc": "boolean",
"pin": "boolean",
"card": "boolean"
}
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get member group
member_group ID
Response Example (200 OK)
{
"id": "mg_3merk33gt1692dk2p2m1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "string",
"permissions": [
{
"site_id": "site_3merk33gt21kym11een1",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "string",
"schedule_id": "sch_3merk33gt21kyz1f3z1",
"presence": "string",
"access_methods": {
"online": "boolean",
"bluetooth": "boolean",
"mobile_nfc": "boolean",
"pin": "boolean",
"card": "boolean"
}
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit member group
member_group ID
|
name
string |
Group name |
|
permissions
member_group_permission_rule |
Permission rules granted to members of this group. A member can have multiple groups, and the permissions are the union of all the groups. Access is granted if at least one rule matches. |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"name": "string",
"permissions": [
{
"site_id": "site_3merk33gt21kym11een1",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "string",
"schedule_id": "sch_3merk33gt21kyz1f3z1",
"presence": "string",
"access_methods": {
"online": "boolean",
"bluetooth": "boolean",
"mobile_nfc": "boolean",
"pin": "boolean",
"card": "boolean"
}
}
],
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "mg_3merk33gt1692dk2p2m1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "string",
"permissions": [
{
"site_id": "site_3merk33gt21kym11een1",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "string",
"schedule_id": "sch_3merk33gt21kyz1f3z1",
"presence": "string",
"access_methods": {
"online": "boolean",
"bluetooth": "boolean",
"mobile_nfc": "boolean",
"pin": "boolean",
"card": "boolean"
}
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Delete member group
member_group ID
Response Example (200 OK)
{
"id": "mg_3merk33gt1692dk2p2m1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "string",
"permissions": [
{
"site_id": "site_3merk33gt21kym11een1",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"action_id": "string",
"schedule_id": "sch_3merk33gt21kyz1f3z1",
"presence": "string",
"access_methods": {
"online": "boolean",
"bluetooth": "boolean",
"mobile_nfc": "boolean",
"pin": "boolean",
"card": "boolean"
}
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Schedules
schedule
|
id
string (schedule_id) |
schedule ID |
|
organization_id
string (organization_id) |
organization ID |
|
name
string |
Name |
|
weekdays
object[] |
Array of length 7 containing the time ranges for each weekday. Week starts on Monday, i.e. index 0 is Monday and index 6 is Sunday. User is granted access according to the schedule if the current time (in the site's local time zone) falls within one of the specified ranges. Range start and end are specified in number of seconds starting from 00:00. Start and end must be between 0 and 86400. End must be greater than start. Ranges within a single day must not overlap. |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "sch_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "Mon-Fri 9AM-6PM",
"weekdays": [
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": []
},
{
"ranges": []
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List schedules
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Search parameter
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
|
data
schedule |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "sch_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "Mon-Fri 9AM-6PM",
"weekdays": [
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": []
},
{
"ranges": []
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create schedule
|
name
string |
Name |
|
weekdays
object[] |
Array of length 7 containing the time ranges for each weekday. Week starts on Monday, i.e. index 0 is Monday and index 6 is Sunday. User is granted access according to the schedule if the current time (in the site's local time zone) falls within one of the specified ranges. Range start and end are specified in number of seconds starting from 00:00. Start and end must be between 0 and 86400. End must be greater than start. Ranges within a single day must not overlap. |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"name": "string",
"weekdays": [
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": []
},
{
"ranges": []
}
],
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "sch_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "Mon-Fri 9AM-6PM",
"weekdays": [
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": []
},
{
"ranges": []
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get schedule
schedule ID
Response Example (200 OK)
{
"id": "sch_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "Mon-Fri 9AM-6PM",
"weekdays": [
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": []
},
{
"ranges": []
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit schedule
schedule ID
|
name
string |
Name |
|
weekdays
object[] |
Array of length 7 containing the time ranges for each weekday. Week starts on Monday, i.e. index 0 is Monday and index 6 is Sunday. User is granted access according to the schedule if the current time (in the site's local time zone) falls within one of the specified ranges. Range start and end are specified in number of seconds starting from 00:00. Start and end must be between 0 and 86400. End must be greater than start. Ranges within a single day must not overlap. |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"name": "string",
"weekdays": [
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": []
},
{
"ranges": []
}
],
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "sch_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "Mon-Fri 9AM-6PM",
"weekdays": [
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": []
},
{
"ranges": []
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Delete schedule
schedule ID
Response Example (200 OK)
{
"id": "sch_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "Mon-Fri 9AM-6PM",
"weekdays": [
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": [
{
"start": 32400,
"end": 64800
}
]
},
{
"ranges": []
},
{
"ranges": []
}
],
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Cards
Cards configured for a particular organization
card
|
id
string (card_id) |
card ID |
|
organization_id
string (organization_id) |
organization ID |
|
name
string |
Card name in organization. |
|
uid
string |
ISO14443 UID for the card. Always 4, 7 or 10 bytes, encoded in hex. |
|
printed_code
string |
Unique code physically printed on the card. |
|
metadata
metadata |
Key-value metadata |
Example
{
"id": "crd_3ykdnnld7d57x83eqcm1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "string",
"uid": "041E53F2FF6780",
"printed_code": "WHJSA",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
List cards
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
|
data
card |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "crd_3ykdnnld7d57x83eqcm1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "string",
"uid": "041E53F2FF6780",
"printed_code": "WHJSA",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create card
|
id
string (card_id) |
Card ID. Optional. One of |
|
printed_code
string |
Unique code physically printed on the card. Optional. One of |
|
uid
string |
ISO14443 UID for the card. Always 4, 7 or 10 bytes, encoded in hex. Optional. One of |
|
name
string |
Card name. Optional. |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"id": "crd_3ykdnnld7d57x83eqcm1",
"printed_code": "WHJSA",
"uid": "041E53F2FF6780",
"name": "string",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
{
"id": "crd_3ykdnnld7d57x83eqcm1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "string",
"uid": "041E53F2FF6780",
"printed_code": "WHJSA",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Get cards
Response Example (200 OK)
{
"id": "crd_3ykdnnld7d57x83eqcm1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"name": "string",
"uid": "041E53F2FF6780",
"printed_code": "WHJSA",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Edit card
|
name
string |
Card name |
|
metadata
metadata |
Key-value metadata |
Request Example
{
"name": "string",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (200 OK)
Delete card
Response Example (200 OK)
Events
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,
useas verb, and the gadget action as object. - Member editions are reported with the admin user who did the action in the subject,
editas 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.
event
|
id
string (event_id) |
event ID |
|
organization_id
string (organization_id) |
organization ID |
|
subject
event_subject |
|
|
verb
string create, edit, delete, use |
|
|
object
event_object |
|
|
created_at
string (date-time) |
Creation time for this object. |
Example
{
"id": "evt_3merk33gt21kym11een1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"subject": {
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_email_id": "me_3rkd7ya2pnjysjqbluj1",
"member_magic_link_id": "mml_3rkd2f2mv925ptvpgblh",
"member_pin_id": "mp_3rkd2fmgmmdh1dgkvluh",
"member_card_id": "mc_3yd55tbrelfxhjjvkdqh",
"member_token_id": "mt_3yd55tbrelfxhjjvkdqh",
"client": {
"device_type": "phone",
"user_agent": null,
"os": "Android",
"os_version": "16",
"device_manufacturer": "Google",
"device_model": "Pixel 8",
"app_package_name": "app.akiles",
"app_name": "Akiles",
"app_version": "4.3.0",
"app_version_code": "6994",
"browser": null,
"browser_version": null,
"sdk_version": "2.0.0",
"sdk_commit": "39620f94fdcf3e56"
},
"ip_address": "1.2.3.4",
"access_method": "online"
},
"verb": "use",
"object": {
"type": "gadget_action",
"device_id": "dev_3merk33gt3l525ryhcmh",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"gadget_action_id": "open",
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_email_id": "me_3rkd7ya2pnjysjqbluj1",
"member_magic_link_id": "mml_3rkd2f2mv925ptvpgblh",
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"member_group_association_id": "mga_3rkd81x2hc3qluv56pl1",
"member_pin_id": "mp_3rkd2fmgmmdh1dgkvluh",
"member_card_id": "mc_3yd55tbrelfxhjjvkdqh",
"member_token_id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"webhook_id": "wh_3merk33gt21kyz1f3z1",
"hardware_id": "hw_3merk33gt2a7grgmljhh",
"card_id": "crd_3ykdnnld7d57x83eqcm1"
},
"created_at": "2024-03-13T16:56:51.766836837Z"
}
event_subject
|
member_id
string (member_id) |
member ID |
|
member_email_id
string (member_email_id) |
member_email ID |
|
member_magic_link_id
string (member_magic_link_id) |
member_magic_link ID |
|
member_pin_id
string (member_pin_id) |
member_pin ID |
|
member_card_id
string (member_card_id) |
member_card ID |
|
member_token_id
string (member_token_id) |
member_token ID |
|
client
client_info |
|
|
ip_address
string |
|
|
access_method
string online, bluetooth, mobile_nfc, pin, card |
Example
{
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_email_id": "me_3rkd7ya2pnjysjqbluj1",
"member_magic_link_id": "mml_3rkd2f2mv925ptvpgblh",
"member_pin_id": "mp_3rkd2fmgmmdh1dgkvluh",
"member_card_id": "mc_3yd55tbrelfxhjjvkdqh",
"member_token_id": "mt_3yd55tbrelfxhjjvkdqh",
"client": {
"device_type": "phone",
"user_agent": null,
"os": "Android",
"os_version": "16",
"device_manufacturer": "Google",
"device_model": "Pixel 8",
"app_package_name": "app.akiles",
"app_name": "Akiles",
"app_version": "4.3.0",
"app_version_code": "6994",
"browser": null,
"browser_version": null,
"sdk_version": "2.0.0",
"sdk_commit": "39620f94fdcf3e56"
},
"ip_address": "1.2.3.4",
"access_method": "online"
}
event_object
|
type
string device, gadget, gadget_action, member, member_email, member_magic_link, member_group, member_group_association, member_pin, member_card, member_token, organization, site, webhook, hardware, card |
|
|
device_id
string (device_id) |
device ID |
|
gadget_id
string (gadget_id) |
gadget ID |
|
gadget_action_id
string |
gadget_action ID |
|
member_id
string (member_id) |
member ID |
|
member_email_id
string (member_email_id) |
member_email ID |
|
member_magic_link_id
string (member_magic_link_id) |
member_magic_link ID |
|
member_group_id
string (member_group_id) |
member_group ID |
|
member_group_association_id
string (member_group_association_id) |
member_group_association ID |
|
member_pin_id
string (member_pin_id) |
member_pin ID |
|
member_card_id
string (member_card_id) |
member_card ID |
|
member_token_id
string (member_token_id) |
member_token ID |
|
organization_id
string (organization_id) |
organization ID |
|
site_id
string (site_id) |
site ID |
|
webhook_id
string (webhook_id) |
webhook ID |
|
hardware_id
string (hardware_id) |
hardware ID |
|
card_id
string (card_id) |
card ID |
Example
{
"type": "gadget_action",
"device_id": "dev_3merk33gt3l525ryhcmh",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"gadget_action_id": "open",
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_email_id": "me_3rkd7ya2pnjysjqbluj1",
"member_magic_link_id": "mml_3rkd2f2mv925ptvpgblh",
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"member_group_association_id": "mga_3rkd81x2hc3qluv56pl1",
"member_pin_id": "mp_3rkd2fmgmmdh1dgkvluh",
"member_card_id": "mc_3yd55tbrelfxhjjvkdqh",
"member_token_id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"webhook_id": "wh_3merk33gt21kyz1f3z1",
"hardware_id": "hw_3merk33gt2a7grgmljhh",
"card_id": "crd_3ykdnnld7d57x83eqcm1"
}
client_info
|
device_type
string |
|
|
user_agent
string |
|
|
os
string |
|
|
os_version
string |
|
|
device_manufacturer
string |
|
|
device_model
string |
|
|
app_package_name
string |
|
|
app_name
string |
|
|
app_version
string |
|
|
app_version_code
string |
|
|
browser
string |
|
|
browser_version
string |
|
|
sdk_version
string |
|
|
sdk_commit
string |
Example
{
"device_type": "phone",
"user_agent": null,
"os": "Android",
"os_version": "16",
"device_manufacturer": "Google",
"device_model": "Pixel 8",
"app_package_name": "app.akiles",
"app_name": "Akiles",
"app_version": "4.3.0",
"app_version_code": "6994",
"browser": null,
"browser_version": null,
"sdk_version": "2.0.0",
"sdk_commit": "39620f94fdcf3e56"
}
List events
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
|
data
event |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "evt_3merk33gt21kym11een1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"subject": {
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_email_id": "me_3rkd7ya2pnjysjqbluj1",
"member_magic_link_id": "mml_3rkd2f2mv925ptvpgblh",
"member_pin_id": "mp_3rkd2fmgmmdh1dgkvluh",
"member_card_id": "mc_3yd55tbrelfxhjjvkdqh",
"member_token_id": "mt_3yd55tbrelfxhjjvkdqh",
"client": {
"device_type": "phone",
"user_agent": null,
"os": "Android",
"os_version": "16",
"device_manufacturer": "Google",
"device_model": "Pixel 8",
"app_package_name": "app.akiles",
"app_name": "Akiles",
"app_version": "4.3.0",
"app_version_code": "6994",
"browser": null,
"browser_version": null,
"sdk_version": "2.0.0",
"sdk_commit": "39620f94fdcf3e56"
},
"ip_address": "1.2.3.4",
"access_method": "online"
},
"verb": "use",
"object": {
"type": "gadget_action",
"device_id": "dev_3merk33gt3l525ryhcmh",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"gadget_action_id": "open",
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_email_id": "me_3rkd7ya2pnjysjqbluj1",
"member_magic_link_id": "mml_3rkd2f2mv925ptvpgblh",
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"member_group_association_id": "mga_3rkd81x2hc3qluv56pl1",
"member_pin_id": "mp_3rkd2fmgmmdh1dgkvluh",
"member_card_id": "mc_3yd55tbrelfxhjjvkdqh",
"member_token_id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"webhook_id": "wh_3merk33gt21kyz1f3z1",
"hardware_id": "hw_3merk33gt2a7grgmljhh",
"card_id": "crd_3ykdnnld7d57x83eqcm1"
},
"created_at": "2024-03-13T16:56:51.766836837Z"
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Get event
event ID
Response Example (200 OK)
{
"id": "evt_3merk33gt21kym11een1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"subject": {
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_email_id": "me_3rkd7ya2pnjysjqbluj1",
"member_magic_link_id": "mml_3rkd2f2mv925ptvpgblh",
"member_pin_id": "mp_3rkd2fmgmmdh1dgkvluh",
"member_card_id": "mc_3yd55tbrelfxhjjvkdqh",
"member_token_id": "mt_3yd55tbrelfxhjjvkdqh",
"client": {
"device_type": "phone",
"user_agent": null,
"os": "Android",
"os_version": "16",
"device_manufacturer": "Google",
"device_model": "Pixel 8",
"app_package_name": "app.akiles",
"app_name": "Akiles",
"app_version": "4.3.0",
"app_version_code": "6994",
"browser": null,
"browser_version": null,
"sdk_version": "2.0.0",
"sdk_commit": "39620f94fdcf3e56"
},
"ip_address": "1.2.3.4",
"access_method": "online"
},
"verb": "use",
"object": {
"type": "gadget_action",
"device_id": "dev_3merk33gt3l525ryhcmh",
"gadget_id": "gad_3merk33gt1hnl6pvbu71",
"gadget_action_id": "open",
"member_id": "mem_3merk33gt7ml3tde71f3",
"member_email_id": "me_3rkd7ya2pnjysjqbluj1",
"member_magic_link_id": "mml_3rkd2f2mv925ptvpgblh",
"member_group_id": "mg_3merk33gt1692dk2p2m1",
"member_group_association_id": "mga_3rkd81x2hc3qluv56pl1",
"member_pin_id": "mp_3rkd2fmgmmdh1dgkvluh",
"member_card_id": "mc_3yd55tbrelfxhjjvkdqh",
"member_token_id": "mt_3yd55tbrelfxhjjvkdqh",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"site_id": "site_3merk33gt21kym11een1",
"webhook_id": "wh_3merk33gt21kyz1f3z1",
"hardware_id": "hw_3merk33gt2a7grgmljhh",
"card_id": "crd_3ykdnnld7d57x83eqcm1"
},
"created_at": "2024-03-13T16:56:51.766836837Z"
}
Webhooks
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 ofobject.typeto match. This must be specified, i.e. it's NOT possible to subscribe to all object types.verb: The value ofverbto match. If it's set tonullit 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.
webhook_filter_rule
|
object_type
string gadget, gadget_action, member, member_group, organization, site |
Object type of the event. |
|
verb
string create, edit, delete, use |
Action verb of the event. If null, matches all verbs. |
Example
{
"object_type": "gadget_action",
"verb": "use"
}
webhook
|
id
string (webhook_id) |
webhook ID |
|
organization_id
string (organization_id) |
organization ID |
|
filter
webhook_filter_rule |
Array of event filter rules. 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. |
|
url
string |
URL the events are sent to. |
|
secret
string |
Secret used to sign webhooks. Visible only in the response for the creation API call. |
|
is_enabled
boolean |
True if this webhook is enabled. When false, no webhooks are sent. |
|
is_deleted
boolean |
True if this object has been deleted. |
|
created_at
string (date-time) |
Creation time for this object. |
Example
{
"id": "wh_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"filter": [
{
"object_type": "gadget_action",
"verb": "use"
}
],
"url": "https://example.com/hook",
"secret": "f305d484fd10de285b00bb203659e863",
"is_enabled": true,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z"
}
List webhooks
Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
Items per page.
Sort order. Field name, followed by :asc or :desc. Defaults to created_at:desc if that field exists, otherwise id:desc. Depending on the endpoint, sorting on some fields might not be supported.
|
data
webhook |
|
|
has_next
boolean |
|
|
cursor_next
string (cursor) |
Response Example (200 OK)
{
"data": [
{
"id": "wh_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"filter": [
{
"object_type": "gadget_action",
"verb": "use"
}
],
"url": "https://example.com/hook",
"secret": "f305d484fd10de285b00bb203659e863",
"is_enabled": true,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z"
}
],
"has_next": true,
"cursor_next": "i9vmCnOgONT2AjUMCn1K1N5cJg=="
}
Create webhook
|
filter
webhook_filter_rule |
Array of event filter rules. |
|
url
string |
URL the events are sent to. |
|
is_enabled
boolean |
True if this webhook is enabled. When false, no webhooks are sent. |
Request Example
{
"filter": [
{
"object_type": "gadget_action"
}
],
"url": "https://example.com/hook",
"is_enabled": true
}
Response Example (200 OK)
{
"id": "wh_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"filter": [
{
"object_type": "gadget_action",
"verb": "use"
}
],
"url": "https://example.com/hook",
"secret": "f305d484fd10de285b00bb203659e863",
"is_enabled": true,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z"
}
Get webhook
webhook ID
Response Example (200 OK)
{
"id": "wh_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"filter": [
{
"object_type": "gadget_action",
"verb": "use"
}
],
"url": "https://example.com/hook",
"secret": "f305d484fd10de285b00bb203659e863",
"is_enabled": true,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z"
}
Edit webhook
webhook ID
|
filter
webhook_filter_rule |
Array of event filter rules. |
|
url
string |
URL the events are sent to. |
|
is_enabled
boolean |
True if this webhook is enabled. When false, no webhooks are sent. |
Request Example
{
"filter": [
{
"object_type": "gadget_action"
}
],
"url": "https://example.com/hook",
"is_enabled": true
}
Response Example (200 OK)
{
"id": "wh_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"filter": [
{
"object_type": "gadget_action",
"verb": "use"
}
],
"url": "https://example.com/hook",
"secret": "f305d484fd10de285b00bb203659e863",
"is_enabled": true,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z"
}
Delete webhook
webhook ID
Response Example (200 OK)
{
"id": "wh_3merk33gt21kyz1f3z1",
"organization_id": "org_3merk33gt1v9ypgfzrp1",
"filter": [
{
"object_type": "gadget_action",
"verb": "use"
}
],
"url": "https://example.com/hook",
"secret": "f305d484fd10de285b00bb203659e863",
"is_enabled": true,
"is_deleted": false,
"created_at": "2024-03-13T16:56:51.766836837Z"
}