Introduction
Welcome to the CANDY HOUSE Developer Site! We use RESTful API to provide basic manipulation of the Sesame smart lock, including:
- Lock and unlock Sesame via the Wi-Fi Access Point
- Get Sesame lock/unlock status
- Get battery status
Many new functions are still under development and will be coming soon, so stay tuned!
Please note that in order to enable API for your Sesame, you must be the owner of Sesame and have it paired with the Wi-Fi Access Point.
To set up your Wi-Fi Access Point, follow these instructions to link your Wi-Fi Access Point to your home Wi-Fi network and pair it with your Sesame. Once you have done so, go to Sesame Status > Change Settings > Integrations and toggle this setting to ON to enable the API.
If you created your account with Google or Facebook login, please go to Account Settings > Change Password and enter a new password for your account. This will be the password for your CANDY HOUSE login.
If you would like to suggest changes to the documentation or if you find any bugs, please feel free to contact us.
Versioning
The current API version is v1
, so every endpoint should be prefixed with:
https://api.candyhouse.co/v1
Parameters
Pass parameter in json body
curl -H "Content-Type: application/json" \
-X POST -d '{"param1":"value1", "param2":"value2"}'
Pass parameter in query strings
curl "https://api.candyhouse.co/v1/endpoint?param1=value1¶m2=value2"
Always pass parameters in json body for POST and query strings for GET.
Timestamp
Timestamp examples
2017-01-02T03:04:05Z
2017-01-02T03:04:05.789Z
We use ISO8601 for the timestamp format.
Authentication
curl -H "X-Authorization: YOUR_AUTH_TOKEN"
After successfully logging in, you will get an auth token. Each login-required request needs to have the auth token set in the X-Authorization
header.
Login API
curl -H "Content-Type: application/json" \
-X POST -d '{"email":"abc@i-lovecandyhouse.co", "password":"super-strong-password"}' \
https://api.candyhouse.co/v1/accounts/login
{
"authorization": "d015cf1353d21a14f392835bceb56d53649e447e3aebe440cef9d"
}
POST /accounts/login
Post Body
Parameter | Type | Description |
---|---|---|
email |
string |
(required) User email |
password |
string |
(required) User password |
Response Fields
Parameter | Type | Description |
---|---|---|
authorization |
string |
Login auth token |
Expiration
- Token expires in 30 days.
- Token expires if password is changed.
Sesame API
Get Sesame list
curl -H "X-Authorization: YOUR_AUTH_TOKEN" \
https://api.candyhouse.co/v1/sesames
{
"sesames": [
{
"device_id": "ABC1234567",
"nickname": "Front door",
"is_unlocked": true,
"api_enabled": true,
"battery": 100
}, {
"device_id": "DEF7654321",
"nickname": "Back door",
"is_unlocked": false,
"api_enabled": false,
"battery": 80
}
]
}
GET /sesames
Response Fields
Parameter | Type | Description |
---|---|---|
sesames |
array | Array of Sesames |
sesames[i].device_id |
string |
Sesame ID |
sesames[i].nickname |
string |
Sesame nickname |
sesames[i].is_unlocked |
boolean |
Sesame is unlocked |
sesames[i].api_enabled |
boolean |
Sesame is API-enabled (Sesame must be paired with Wi-Fi Access Point and have API enabled in app) |
sesames[i].battery |
integer | Sesame battery status |
Get Sesame status
curl -H "X-Authorization: YOUR_AUTH_TOKEN" \
https://api.candyhouse.co/v1/sesames/ABCD12345
{
"nickname": "Front door",
"is_unlocked": true,
"api_enabled": true,
"battery": 100
}
GET /sesames/{sesameId}
Response Fields
Parameter | Type | Description |
---|---|---|
nickname |
string |
Sesame nickname |
is_unlocked |
boolean |
Sesame is unlocked |
api_enabled |
boolean |
Sesame is API-enabled (Sesame must be paired with Wi-Fi Access Point and have API enabled in app) |
battery |
integer | Sesame battery status |
Control Sesame
curl -H "X-Authorization: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-X POST -d '{"type":"lock"}' \
https://api.candyhouse.co/v1/sesames/ABCD12345/control
# 204 No content
''
POST /sesames/{sesameId}/control
Post Body
Parameter | Type | Description |
---|---|---|
type |
string |
(required) lock or unlock |
Response Types
Code | Title | Description |
---|---|---|
200 | OK | Request was successful |
204 | No content | Request was successful; no response received |
400 | Bad request | Bad request |
401 | Unauthorized | Your authorization header is missing or expired |
403 | Forbidden | You don’t have permission to do this |
404 | Not found | The resource does not exist |
50X | Internal Server Error | Oops, please notify CANDY HOUSE of server error |
Errors
Check the tables below for descriptions of each error code:
General Bad Request (400)
Error Code | Description |
---|---|
10000 | Required field cannot be empty |
10001 | Email is invalid |
10002 | Wrong email or password |
10005 | Wrong control type; control must be “lock” or “unlock” |
11002 | Sesame not found |
Unauthorized (401)
Error Code | Description |
---|---|
20000 | Missing auth token |
20001 | Wrong auth token |
20002 | Auth token expired |
20003 | Auth token expired due to password change |
20004 | Auth user account has been deleted |
Permission Error (403)
Error Code | Description |
---|---|
30000 | Owner permission required |
31000 | Account email has not been verified |
31001 | Account is locked |
32000 | Cloud API not enabled |
Server Error (500)
Error Code | Description |
---|---|
5xxxx | Internal server failure |
Third-Party Libraries & Plugins
We love seeing what awesome things Sesame users are doing with our cloud API!
Have something to share? Email us and we’ll be happy to add it to the list!
Libraries using V3 API
Pysesame2
by Anonymous
Sesame.NET
by Ben Randall
“A .NET client for the Sesame API.”
Homebridge-Sesame
“Homebridge plugin for the Sesame smart lock.”
Sesame/SmartThings Integration
by tobycth3
“Integration between Sesame API and SmartThings.”
GSuiteScript for Sesame API
by Jerming Gu
“Integrate Google Apps with Sesame and lock/unlock Sesame from Google Sheets.”
Home Assistant Sesame
“The sesame platform allows you to control your Sesame smart locks made by CANDY HOUSE, Inc.”
Libraries using V1 & V2 API
Pysesame
by Albert Lee
“Python API for controlling Sesame smart locks made by CANDY HOUSE, Inc.”
QSesame
by Brendan
“QSesame is a Homebridge plugin that allows you to control Sesame smart locks with Siri by integrating with HomeKit.”
Sesame Ruby
“This gem provides a simple Ruby wrapper around the CANDY HOUSE Sesame API to control Sesame Bluetooth and Internet-connected locks.” (source)
Sesame API Tutorial
Introduction
In this tutorial, you will learn how to get status updates for your Sesame as well as lock and unlock your Sesame remotely via your computer. You will do so by making GET and POST requests to Sesame’s RESTful API using the free Postman app.
To complete this tutorial, you must have the following:
- Sesame smart lock
- Wi-Fi Access Point
- Computer with internet access
Before You Start
You must be the owner of Sesame to enable the API.
You must have a Wi-Fi Access Point (instructions here) properly set up and paired with your Sesame.
Make sure to update your Sesame app to the latest version and have cloud integration enabled for your Sesame under Status > Change Settings > Integrations.
If you created your CANDY HOUSE account using Google or Facebook login, you must open your Sesame app, go to Account Settings, then select Change Password. Enter a new password and enter the reset code sent to your email. This will be the password for your CANDY HOUSE account which you will need to use in the login step. If you do not do this, you will not have a password for your CANDY HOUSE account and you will receive the Account Locked error.
Keep the Sesame app closed while using the API; if it’s open it will prevent the API from connecting to your Sesame. Only one device can connect to Sesame at a time.
Getting Started with Postman
Download the free Postman app and create an account. Make sure you’ve downloaded the latest version, which at the time of creating this tutorial is version 5.3.2.
Create an account if you haven’t already, and login to the app. We recommend unchecking “Show this window on launch.” Close the launch screen to begin.
Login to CANDY HOUSE
First, we need to get the authorization token so the API can verify the authorization for your requests. Enter the following information in the open tab:
- Change GET to POST
- Enter the request URL: https://api.candyhouse.co/v1/accounts/login
- Select the Body tab
- Select raw
- Select JSON (application/json)
- Type your email and password in the text field using the template provided, replacing the username and password with your own. Be sure to use the same CANDY HOUSE email address you used to register your Sesame:
{"email":"username@ilovecandyhouse.co", "password":"your-own-password"}
After you’ve confirmed you’ve entered everything correctly, click the blue Send button. If your request is successful, the API will return the status 200 plus your authorization token. Keep the tab open, you will need to copy/paste the authorization token for the following steps.
Note: Once you have copy/pasted the token, you don’t need to login again in the future. Logging in again will change the token, which means you will have to update all of your requests, so we do NOT recommend logging in again once you’ve gotten the token. If you do, be sure to update the authorization token in the header for all of your saved requests, or ele they won’t work.
TIP: Save Your Sesame Token as a Preset
You can save the token as a preset so you don’t have to keep copy/pasting the authorization token in the following steps! On an open tab, do the following:
- Select the Headers tab
- Click Presets
- Click Manage Presets
- Click Add
Enter the following information:
- Give your Preset a name, such as: Sesame Token
- Enter the name of your key: X-Authorization
- Copy and paste the authorization token from your login tab in the Value field. Make sure you select only the string of letters and numbers with no quotation marks or spaces.
- When you’re done, click Add.
Next time you want to use your authorization token, click Preset and select Sesame Token to automatically input the information.
Request Sesame List
Next, we will check if the token is correct by requesting a list of Sesames for which you are an owner or manager. Please note that you will only be able to use the API for Sesames for which you are the owner. Open a new tab by clicking on the plus sign next to your tab. In the new tab, enter the following information:
- Leave GET as GET
- Enter the request URL: https://api.candyhouse.co/v1/sesames
- Select the Headers tab
- Add your Sesame Token preset or do the following:
- Enter the name of your key: X-Authorization
- Copy and paste the authorization token in the Value field. Make sure you select only the string of letters and numbers with no quotation marks or spaces.
Once you’ve confirmed all of the above is correct, click the blue Send button. If your request is successful, the API will return status 200 plus a list of Sesames owned or managed by the CANDY HOUSE account you used to login, as well as the following information for each Sesame:
- Device ID
- Nickname
- Lock status (true = unlocked, false = locked)
- API enabled
- Battery percentage
Keep the tab open because you will need the device ID of your Sesame for the following steps. You can save this request by clicking the Save button. You can name the request “List Sesames” or similar so you won’t need to repeat the above the next time you’d like to see your list of Sesames.
Request Sesame Status
Next, we will request the status for an API-enabled Sesame on your list using its device ID. Open a new tab, and enter the following information:
- Leave GET as GET
- For the request URL, enter the following but change “{sesameID}” to the ID of a Sesame you own that is API-enabled: https://api.candyhouse.co/v1/sesames/{sesameID}
- Select the Headers tab
- Add your Sesame Token preset or do the following:
- Enter the name of your key: X-Authorization
- Return to one of your previous tabs and copy the token. Return to your new tab and paste the authorization token in the Value field
Once you’ve confirmed everything is correct, click the blue Send button. If your request is successful, the API will return status 200 plus the status of the Sesame with the given ID, including the following:
- Nickname
- Lock status (true = unlocked, false = locked)
- API enabled
- Battery percentage
Copy the request URL including your Sesame ID to your clipboard as we will need to use it for the next step.
You can save this request by clicking the Save button. You can name the request “Get Sesame Status” or similar so you won’t need to repeat the above the next time you’d like to request the status for your Sesame.
Unlock Sesame
Next we will pass a command to unlock Sesame. Open a new tab, and enter the following information:
- Change GET to POST
- Paste the request URL from your clipboard and add “/control” at the end so it becomes: https://api.candyhouse.co/v1/sesames/{sesameID}/control
- Select the Headers tab
- Add your Sesame Token preset or do the following:
- Enter the name of your key: X-Authorization
- Return to one of your previous tabs and copy the token. Return to your new tab and paste the authorization token in the Value field
Next, enter the following:
- Select the Body tab
- Select raw
- Select JSON (application/json)
- In the text field, type the following:
{"type":"unlock"}
Make sure the information in both the Headers and Body section is correct, then click the blue Send button. If your request is successful, the API will return status 204 (no content) and execute the command. Status 204 is returned when the request is successful and the API doesn’t return any additional information beyond carrying out the command. 200 was returned for previous requests because the API returned information such as token, list, or status.
You can save this request by clicking the Save button. You can name the request “Unlock Sesame” or similar so you won’t need to repeat the above the next time you’d like to unlock your Sesame.
Lock Sesame
Now it’s time to lock Sesame. Once you’ve saved the unlock request, click on the three circles next to the plus sign. Select “Duplicate Current Tab” to create a copy of your Unlock Sesame request.
In the duplicated tab, do the following:
- Select the Body tab
- In the text field, change the content to the following:
{"type":"lock"}
Click the blue Send button. If the request is successful, the API will return status 204.
You can save this request by clicking the arrow next to the Save button and selecting Save As. You can name the request “Lock Sesame" or similar so you won’t need to repeat the above the next time you’d like to lock your Sesame.
Saving Your Requests
If you haven’t already, be sure to save each of your requests by clicking the Save button and giving the request a name that describes its function.
Create a collection to save all your Sesame requests in the same folder for easier access.
The next time you’d like to send a request, you can either click on the tab or find your request in your Sesame collection. Click the Send button to make the request.
Note: We do NOT recommend logging in to CANDY HOUSE again as it will change your token and you will need to update the authorization token in all of your saved requests.
Support
Questions? Comments? Email sesame@candyhouse.co and we’ll be happy to answer your questions! You can also check out the CANDY HOUSE forum for API-related discussions - just sign in with your CANDY HOUSE account email and password.