The following article explains how to integrate Cobot with access control systems such as smart door locks. The goal is to automatically give members access to various parts of your coworking space – depending on their membership level and various other factors.
Our integration will do two things:
For the purpose of this article, we will be integrating with a hypothetical smart lock system called … SmartLock.
SmartLock has its own cloud based management system and offers a simple JSON API that we will use for the integration. The API offers the following endpoints:
Authentication on SmartLock uses a fixed API token sent as an HTTP header called X-Api-Token
.
We will be using various Cobot APIs. Most of all the subscription/webhook API, which allows us to get notified of events such as new members. We will also be using the check-in API for attendance tracking and the booking API to handle room bookings.
Cobot uses OAuth2 for Authentication.
We will be implementing different features in 5 steps, starting with the most simple one.
We will implement our example integration using the Ruby programming language and Sinatra, a simple web framework. The source code should be relatively easy to read even if you don't know Ruby.
For this to work, we need to synchronize members to the SmartLock system when they start, and remove them again when they cancel.
Before we can start, we need access to both APIs – Cobot and SmartLock. We already have the API token for SmartLock. To get an OAuth token for Cobot, we need to implement one of the OAuth flows — or just create a client and copy/paste a token to get started.
First we store our access tokens in constants:
COBOT_ACCESST_TOKEN = "cobot-token-1" SMARTLOCK_API_TOKEN = "sl-token-123"
In order get notified when a new member is added to our Cobot space, we are going to create a webhook for the membership_confirmed event using the Cobot subscription API.
Here’s the call to create a subscription for our Cobot test space (it lives under the subdomain "test-space"). We are using the rest-client library/gem to make HTTP requests.
RestClient.post "https://test-space.cobot.me/api/subscriptions", { event: "confirmed_membership", callback_url: "https://cobot-smartlock-integration.com/membership_confirmation" }, { 'Authorization': "Bearer #{COBOT_ACCESST_TOKEN}" }
We subscribe to the confirmed_membership event and pass the matching endpoint of our integration, to be called whenever a new member is confirmed on Cobot.
Here’s our webhook handler:
require 'sinatra' post "/membership_confirmation" do # the webhook passes a url param that points to the newly confirmed membership membership = RestClient.get(params['url']) if membership['email'] RestClient.post( # register user on SmartLock 'https://api.smartlock.com/users', {email: membership['email]}, {'X-Api-Token': SMARTLOCK_API_TOKEN} ) end end
Whenever a new membership on Cobot is confirmed, the endpoint sends a user registration request to SmartLock. We assume that SmartLock will handle things from here, for example send an invite to download an app, notify admins to prepare a key fob etc. Any permissions can be configured on the SmartLock website.
TBD
Cobot offers a check-in mechanism which opens the door (sic) for two features:
In order to enable check-ins, we need the SmartLock API to provide a webhook for when a member opens a lock. In addition, we need to map SmartLock users to Cobot memberships.
To create a mapping, let’s extend our user registration endpoint (we are leaving out the API headers to make the code more readable):
post "/membership_confirmation" do membership = RestClient.get(params['url']) # the webhook passes a url param that points to the newly confirmed membership if membership['email'] response = RestClient.post( 'https://api.smartlock.com/users', { email: membership['email'] } ) user_id = JSON.parse(response)['id'] RestClient.post( "https://test-space.cobot.me/api/check_in_tokens", { membership_id: membership['id'], token: user_id } ) end end
Here we register the user_id that we got back from the SmartLock API as a so-called check-in token on Cobot. These tokens can later be used to check a member in without knowing their id or another identifier.
Now all we need to do is add a handler for the lock-opened webhook that we receive from SmartLock:
# assumed webhook payload: # event: {"user": {"id": "the-user-id", ...}, ...} post "/lock_open" do user_id = JSON.parse(params['event'])['user']['id'] RestClient.post( "https://tests-space.cobot.me/api/check_ins", {"token": user_id} ) end
When receiving a lock-open event from SmartLock, we pull the user id from the payload and check the member in on Cobot. This will use up a time pass if applicable and generate the relevent statistics on Cobot.
TBD
TBD
TBD
TBD