NAV Navbar
Logo
shell

Introduction

Welcome to the CANDY HOUSE Developer Site! We use RESTful API to provide basic manipulation of the Sesame smart lock, including:

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&param2=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

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

by Andrew Schaper

“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

by Home Assistant

“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

by Michael B. Klein

“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:

  1. Sesame smart lock
  2. Wi-Fi Access Point
  3. Computer with internet access

Before You Start

  1. You must be the owner of Sesame to enable the API.

  2. You must have a Wi-Fi Access Point (instructions here) properly set up and paired with your Sesame.

  3. Make sure to update your Sesame app to the latest version and have cloud integration enabled for your Sesame under Status > Change Settings > Integrations.

  4. 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.

  5. 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

  1. 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. Current Postman Version

  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. Postman Launch Screen

Login to CANDY HOUSE

  1. 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:

    1. Change GET to POST
    2. Enter the request URL: https://api.candyhouse.co/v1/accounts/login
    3. Select the Body tab
    4. Select raw
    5. Select JSON (application/json)
    6. 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"}

    Login to CANDY HOUSE

  2. 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.
    Login to CANDY HOUSE

  3. 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

  1. 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:

    1. Select the Headers tab
    2. Click Presets
    3. Click Manage Presets
    4. Click Add

    Manage Presets

  2. Enter the following information:

    1. Give your Preset a name, such as: Sesame Token
    2. Enter the name of your key: X-Authorization
    3. 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.
    4. When you’re done, click Add.

    Add Preset

  3. Next time you want to use your authorization token, click Preset and select Sesame Token to automatically input the information. Add Sesame Token

Request Sesame List

  1. 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:

    1. Leave GET as GET
    2. Enter the request URL: https://api.candyhouse.co/v1/sesames
    3. Select the Headers tab
    4. Add your Sesame Token preset or do the following:
      1. Enter the name of your key: X-Authorization
      2. 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.

    Request Sesame List

  2. 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:

    1. Device ID
    2. Nickname
    3. Lock status (true = unlocked, false = locked)
    4. API enabled
    5. Battery percentage

    Sesame List

  3. 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

  1. 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:

    1. Leave GET as GET
    2. 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}
    3. Select the Headers tab
    4. Add your Sesame Token preset or do the following:
      1. Enter the name of your key: X-Authorization
      2. 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

    Request Sesame Status

  2. 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:

    1. Nickname
    2. Lock status (true = unlocked, false = locked)
    3. API enabled
    4. Battery percentage

    Sesame Status

  3. Copy the request URL including your Sesame ID to your clipboard as we will need to use it for the next step.

  4. 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

  1. Next we will pass a command to unlock Sesame. Open a new tab, and enter the following information:

    1. Change GET to POST
    2. Paste the request URL from your clipboard and add “/control” at the end so it becomes: https://api.candyhouse.co/v1/sesames/{sesameID}/control
    3. Select the Headers tab
    4. Add your Sesame Token preset or do the following:
      1. Enter the name of your key: X-Authorization
      2. 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

    Unlock Sesame Header

  2. Next, enter the following:

    1. Select the Body tab
    2. Select raw
    3. Select JSON (application/json)
    4. In the text field, type the following: {"type":"unlock"}

    Unlock Sesame Body

  3. 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. Unlock Sesame Successful

  4. 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

  1. 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. Duplicate Tab

  2. In the duplicated tab, do the following:

    1. Select the Body tab
    2. In the text field, change the content to the following: {"type":"lock"}

    Change to lock

  3. Click the blue Send button. If the request is successful, the API will return status 204.

  4. 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. Save As

Saving Your Requests

  1. 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. Save Request

  2. Create a collection to save all your Sesame requests in the same folder for easier access. Collection

  3. 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. Access Saved Requests

  4. 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.