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:
| Field Name | Description |
| door_id | alphanumeric max length 191 chars, used to identify a specific door |
| name | Name for the door |
| active | boolean, true/false, true indicates the door is enabled for use. If false, door should not be allowed to use |
| membership_type_ids | An array of unique membership type ids that have access to this door. |
| allow_instructors | boolean, true/false, true indicates that an instructor should be allowed access to this door regardless of membership. |
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).
| Field Name | Required/optional | Description |
| id | optional if door_access_id or barcode_id field is passed, otherwise required. numeric | Unique user id that was assigned to this user by the Hive platform |
| door_access_id | optional if id or barcode_id field is passed, otherwise required. alphanumeric max length 191 chars | Will perform a lookup of user by door access id in the database. This can be any value that would map to the door access method (key card, rfid fob, etc) |
| barcode_id | optional if id or door_access_id is passed, otherwise required. alphanumeric max length 191 chars | Will perform a lookup of user by the assigned barcode id in the Hive platform |
| door_id | required (alphanumeric max length 191 chars) | ID of the door the user is accessing, useful to limit access if there are multiple doors and the user should not have access to all doors. |
| check_only | optional (boolean, true/false) | If the option is omitted or it is passed as falsey, a checkin/access log will be recorded for that user on that door. |
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:
| Field Name | Description |
| user -> id | Numeric User id from the Hive platform, unique amongst all users |
| user -> door_access_id | Alphanumeric max length 191 chars |
| user -> barcode_id | Alphanumeric max length 191 chars |
| user -> first_name | User's first name on record |
| user -> last_name | User's last name on record |
| user -> email | User's email (if enabled on api settings) |
| user -> phone | User's phone number(if enabled on api settings), provided as best attempt at E.164 parsed/formatted value. Blank string if we do not have their phone number |
| user -> is_instructor | Boolean, true/false, false if user is not an instructor, true if the user is considered an instructor or staff. |
| user -> memberships | An array of memberships that the user has on their account that can access a door. A user may have one or more memberships. |
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:
| Field Name | Description |
| membership_id | Numeric, unique to that user's membership instance, never repeated on any other membership |
| membership_type_id | Numeric, designates the type of the membership, shared amongst all the memberships of the same type |
| membership_type_name | String, name of the membership type for this membership. |
| expires | Unix timestamp (seconds since epoch) for when the membership may expire, terminate or renew next |
| door_ids | Array of door ids that the membership grants access to |
/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:
| Field Name | Description |
| users | Array of users (see /access endpoint above for fields) |
| page | Integer, the current page number for the results |
| next_page | Integer or false, if there is another page of results it will be the page number of the next set of results, otherise it will be false. |
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
}
Category > Section:Business Management >Settings
