How to enable the Door Access API

In your Hive admin, visit Settings -> External Door API. Enable the Door Access API and configure the API key. The base endpoint url will be displayed below the API key. Every Hive's API base endpoint url is unique.

About the API

The API is a restful http api. Responses from the API will use standard http status codes and return a json body.

Authenticating requests to the API

Every call to the API must be authenticated with your unique API key. Set the "X-DOOR-API-KEY" http header on all requests with your API key.

API Responses

The API response body will be a json object with a minimum set of status indication fields for success (boolean) to explicitly indicate whether the result operation was successful and message (string/text) which will include any response message for the operation (typically used for error messages when success is false).

Specific Endpoints

/test

If you would like to test the API to verify that you are able to authenticate and parse the response body, create a call to /test on your base endpoint url.

Example Response Body:

{
  "success": true,
  "message": ""
}

/doors

This endpoint will provide a list of doors in the response. Use the http GET method.

Response will contain standard response fields (success and message) along with an array of objects with the following fields:

Example Response Body:

{
  "success": true,
  "message": "",
  "doors": [
    {
      "door_id": "asdf123",
      "name": "Front Door",
      "active": true,
      "membership_type_ids": [1,2,3],
      "allow_instructors": true,
    },
    {
      "door_id": "fdsa321",
      "name": "Back Door",
      "active": true,
      "membership_type_ids": [],
      "allow_instructors": true,
    }
  ]
}

/access

This endpoint will allow you check access and register entry of a user to a specific door. Use the http POST method with a application/x-www-form-urlencoded post body containing the fields below.

Note: If check_only parameter is omitted or falsey, the system will record that the user entered the facility through that specific door id.

You must pass at least one of the following fields to identify the user: id, door_access_id and/or barcode_id. If you pass more than one of those fields, all the fields will be used to match a user (ie if all of them do not match for a specific user, then it will not grant access, success will be false).

Response will contain standard response fields (success and message, success will be false if the user does not have access for any reason, message will explain why the user does not have access) along with the following additional fields:

Example Response Body:

{
  "success": true,
  "message": "",
  "user": {
    "id": 201,
    "door_access_id": "FFCC8899.....",
    "barcode_id": "123456789abc",
    "first_name": "test",
    "last_name": "testerson",
    "is_instructor": false,
    "memberships": [
      {
        "membership_id": 1234,
        "membership_type_id": 1,
        "membership_type_name": "Standard Monthly",
        "expires": 1762369732,
        "door_ids": ["asdf123"],
     },
      {
        "membership_id": 1235,
        "membership_type_id": 3,
        "membership_type_name": "Unlimited Access",
        "expires": 1762369732,
        "door_ids": ["asdf123"],
      }
    ]
  }
}

Explanation of the fields for membership:

/users

This endpoint will provide a paginated list of users who have access to at least one door. This endpoint is only available when it is enabled on the api settings. Each page will list 100 results. Use the http GET method. To request a specific page, pass query parameter ?p=pagenumber on the request url.

Response will contain standard response fields (success and message) along with an array of user objects containing the same fields as the /access endpoint:

Example Response Body:

{
  "success": true,
  "message": "",
  "users": [
    {
      ... see return fields from /access endpoint for user object
    },
    {
      ... see return fields from /access endpoint for user object
    }
  ],
  "page": 1,
  "next_page": false
}