Embedded access

Send a member from your own site or app to the HybridAF web access page, so they can get through the access steps and unlock a door from a phone browser without installing the HybridAF app. Authentication for the other API routes is described on the overview.

How it works

You build a link that carries one encoded value, key. The value identifies the facility and the member and says where the member is. The page does not ask the member to sign in. It reads the key, finds the facility and the member, and walks the member through the same steps the app shows.

  1. Send the member's record to HybridAF through the facility users API, so HybridAF holds a user whose userExternalId matches your ID for the member.
  2. When the member asks to unlock a door, build the key from the five values below and encode it.
  3. Open the link in the member's phone browser.

The link needs no function key. The facility UID and the member's external ID in the key are what HybridAF checks.

Build the key

Join five values with the pipe character, in this order, with no spaces, then encode the whole string as base64.

<facility-uid>|<user-external-id>|<latitude>|<longitude>|<utc-time>
PositionValueTypeDescription
1Facility UIDGUIDThe same facility UID you send as facilityUid on the facility users API. HybridAF support issues it for each facility you connect.
2User external IDstringThe userExternalId you sent for this member through the facility users API. The member must already exist at the facility.
3LatitudenumberThe member’s current latitude in decimal degrees, with a period as the decimal separator.
4LongitudenumberThe member’s current longitude in decimal degrees, with a period as the decimal separator.
5Current timestringThe time you built the link, in UTC, formatted yyyyMMddHHmmss on a 24-hour clock.

HybridAF uses the coordinates to measure how far the member is from the facility's doors when the member asks to unlock. Send the member's actual position at the time you build the link.

Worked example

Plain string:

3f2b8c1e-5d4a-4e7b-9c1d-0a6e2f7b8d41|MEMBER-1042|34.2257|-77.9447|20261112143005

Base64:

M2YyYjhjMWUtNWQ0YS00ZTdiLTljMWQtMGE2ZTJmN2I4ZDQxfE1FTUJFUi0xMDQyfDM0LjIyNTd8LTc3Ljk0NDd8MjAyNjExMTIxNDMwMDU=

Build it in code

From a shell:

printf '%s' "<facility-uid>|<user-external-id>|<latitude>|<longitude>|$(date -u +%Y%m%d%H%M%S)" | base64

From Node.js:

const time = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
const plain = [facilityUid, userExternalId, latitude, longitude, time].join('|');
const key = Buffer.from(plain, 'utf8').toString('base64');
const link = 'https://app.hybridaf.com/Home/GuestAccess?key=' + encodeURIComponent(key);

What the member sees

The link signs the member in and opens the facility page in the HybridAF web app. The page shows:

  • The facility's name, address, phone number when the facility has one, and the member's distance from the facility, worked out from the coordinates in the key.
  • A website button and, where the facility has set them up, waiver, rules and message buttons.
  • One unlock button for each door the member can use. The member taps the button for the door they want.

The facility's own settings decide what else appears. A member who has not accepted the facility's rules or waiver, or who does not pass the facility's access checks, sees a message explaining why in place of the door buttons. Where the facility allows it, the member can request emergency access. Admins at the facility see their admin doors.

Requirements

  • The facility UID from HybridAF support. Contact support to get it for each facility you connect.
  • A member record at the facility whose userExternalId matches the second value in the key.

When the key does not match a facility, or the member is not found at that facility, the page does not open a door. Check the facility UID and the external ID first, then contact support.

Questions about embedded access: contact HybridAF support or call 844-927-4313.