Grant Access

This guide outlines the requirements for implementing access control to specific Access Points or devices. Devices are typically used for opening unit-level smart locks, while Access Points are for common entry points.

ButterflyMX uses the OAuth 2.0 authorization code flow for authentication. This allows residents to authenticate to their ButterflyMX account, authorizing your application to perform actions on their behalf. You will need a button in your application that initiates this authorization process, styled according to ButterflyMX brand guidelines.

Grant Access API

The Grant Access API requires two parameters: Tenant ID and either an Access Point ID or a Device ID.

Example Request Using access_point_id:

POST https://apisandbox.butterflymx.com/v4/door_release_requests

{
  "door_release_request": {
    "access_point_id": 123,
    "tenant_id": 567
  }
}

Example Request Using device_id:

POST https://apisandbox.butterflymx.com/v4/door_release_requests

{
  "door_release_request": {
    "device_id": 123,
    "tenant_id": 567
  }
}

Access Points are used for controlling Intercoms, ACS Controllers, Smart Keypads, and Common Area Smart Locks.
Devices are used for granting access to unit-level smart locks.

Collecting Required Parameters

To collect the necessary parameters (tenant_id, access_point_id, or device_id), use the following APIs.

Get List of Tenants

To retrieve the list of tenants a user has access to, use the following API:

GET https://apisandbox.butterflymx.com/v4/tenants

Example Response:

{
  "data": [
    {
      "created_at": "2022-08-08T18:06:02Z",
      "full_name": null,
      "id": 129227,
      "updated_at": "2023-03-21T16:07:19Z",
      "first_name": "Demo",
      "last_name": "Tenant",
      "building_id": 11743,
      "inactive_after": null,
      "email": "demo.tenant@butterflymx.com",
      "unit": {
        "created_at": "2022-08-12T17:32:36Z",
        "id": 101356,
        "label": "101",
        "updated_at": "2024-07-11T13:30:46Z",
        "floor": "1",
        "building_id": 11743
      }
    }
  ]
}

From this response, note the tenant_id to be used in the door release request, and the building_id to fetch Access Points or Devices.

Get List of Access Points

To get a list of Access Points filtered by building_id, use the following API:

GET https://apisandbox.butterflymx.com/v4/access_points?q[building_id_eq]=11879

Example Response:

{
  "data": [
    {
      "created_at": "2024-06-14T15:04:30Z",
      "id": 24318,
      "name": "AP w/o AG",
      "updated_at": "2024-06-14T15:04:30Z",
      "building_id": 11879,
      "device_ids": []
    },
    {
      "created_at": "2023-03-08T19:02:31Z",
      "id": 3996,
      "name": "CC AP 11",
      "updated_at": "2023-03-08T19:02:31Z",
      "building_id": 11879,
      "device_ids": [37130]
    }
  ]
}

Get List of Devices

To retrieve a list of devices (such as unit-level smart locks), use this API:

GET https://apisandbox.butterflymx.com/v4/devices?q[building_id_eq]=11879

Example Response:

{
  "data": [
    {
      "created_at": "2024-09-15T19:09:33Z",
      "id": 115677,
      "model": null,
      "name": "SmartLock - Sandbox DMC",
      "serial_number": null,
      "updated_at": "2024-09-15T19:09:33Z",
      "building_id": 27865,
      "type": "smart_lock"
    }
  ]
}

Final Door Release Request Example

Once you've collected the required parameters (tenant_id and either device_id or access_point_id), the door release request will look like this:

curl --location 'https://apisandbox.butterflymx.com/v4/door_release_requests' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "door_release_request": {
    "device_id": 115677,
    "tenant_id": 531232
  }
}'