HomeDocumentation

Overview

The Lockitron API is a RESTful JSON API. Every request responds in JSON. The resources follow predictable names and consistent conventions. Status codes are used to convey success, failure, and specific failure conditions.

To make the Lockitron API safe to test with, all examples on this page are using a virtual Lockitron. When you lock or unlock any Lock listed on this page, it will not change the state of a physical Lockitron.

      

GET    https://api.lockitron.com/v2/locks
GET    https://api.lockitron.com/v2/locks/:id
PUT    https://api.lockitron.com/v2/locks/:id

GET    https://api.lockitron.com/v2/locks/:lock_id/keys
POST   https://api.lockitron.com/v2/locks/:lock_id/keys
PUT    https://api.lockitron.com/v2/locks/:lock_id/keys/:id
DELETE https://api.lockitron.com/v2/locks/:lock_id/keys/:id

GET    https://api.lockitron.com/v2/users/:id
GET    https://api.lockitron.com/v2/users/:id?face=small
PUT    https://api.lockitron.com/v2/users/:id

GET    https://api.lockitron.com/v2/locks/:lock_id/activity
DELETE https://api.lockitron.com/v2/locks/:lock_id/activity/:id

      
    

Introduction

The Lockitron API lets you programatically access your Lockitron. It lets you lock and unlock your front door from an API. It lets you programmatically invite people to your Lockitron, modify keys to your Lockitron, and revoke access to your Lockitron.

You could use it to build your own app, hack on some cool projects, or manage an in-house access control system.

We've granted you your own ready-to-use access token to short circuit the OAuth authentication process. They are tied you your individual Lockitron user account and should only be used in personal projects, not applications you want to share with other users.

      
      
    

OAuth

Our OAuth2 implementation is based off of version 22 of the OAuth2 spec. If you want to write simple scripts for your own personal or internal use, then you can use the access token we've automatically generated for you rather than OAuth.

OAuth authentication follows a few steps:

  • Ask the Lockitron user if you can access resources on their account for your application.
  • If they accept, save the returned authentication code
  • Use the authentication code to request an access_token.

We recommend using an OAuth2 library (such as the oauth2 gem) to get up and running quickly.

If you've having trouble, it's likely due to an invalid grant error. Frequently, it's because the authentication code you attempted to use has already been used.

If you're getting a different error, double check that you've filled in all the neccessary query string options and that they're the correct values.

      
      
    

Getting the Authentication Code

Using your client id, you need to direct users to the Lockitron OAuth endpoint. If a user accepts to grant you access, they will be redirected to the Lockitron homepage, with a code option inside the query string. That's the authentication code, so put that somewhere safe.

We've already given you an access token for your demo app, however, if you weren't already pre-authorized you would need to follow the authentication URL and click "Allow". To test this, go to Authorized Applications and click "Revoke" next to your Demo app, then immediately visit the authentication URL.

Properties

client_id:
string The client_id associated with the application you are requesting access for.
response_type:
string Set to authentication_code to pass authentication code in query string with key code or token to pass in URL fragment
redirect_uri:
string The requested redirect URI after a user allows access to your application
state:
string Optional: pass an additional state paramater if needed for your application
      GET https://api.lockitron.com/oauth/authorize
    
      GET https://api.lockitron.com/oauth/authorize
    
      Paste authentication code here
    

Getting the Access Token

An access_token is the credential that gives access to specific user's resources for a specific Lockitron app ("API Demo Application" for example). To get an access_token you'll need to post your client_id, client_secret, grant_type, redirect_uri and code (the authentication code from the previous step) to the token endpoint.

You can get the client_id, client_secret and redirect_uri from your API application.

Using your library of choice or manually posting the parameters to Lockitron, upon success you will be issued an access_token tied to that user and application which is valid for three months.

Properties

client_id:
string The client_id associated with the application you are requesting access for.
client_secret:
string The client_secret associated with the application you are requesting access for.
grant_type:
string Set to authentication_code to pass authentication code in query string with key code or token to pass in URL fragment
redirect_uri:
string The requested redirect URI after a user allows access to your application
code:
string The authentication code granted after a user accepts the request for API access
      POST https://api.lockitron.com/oauth/token
    
      POST https://api.lockitron.com/oauth/token
    
      
    

Errors & Messages

The Lockitron API has a standard format for errors and messages. When something goes wrong, it returns an error. When there is no object to display, it returns a message. Most errors return a 400 status code.

Format

status:
string Can either be: "success" or "error"
message:
string A human-readable message providing detail into what happened
reasons:
array An array of key/value pairs indicating issues with specific keys. The values are messages. The keys are where something went wrong.
      {
  status: "error",
  message: "The requested resource was not found.",
  reasons: [ ]
}
      
    

Webhooks

When you create an API application you can also opt to create a webhook which will inform you of lock and unlock activites that take place on a given lock and relating to a specific user. Users with owner and admin keys will receive information relating to all actitives on the lock.

Format

timestamp:
Unix timestamp The time at which the activity was completed and the webhook called. If there is any latency between when the activity was created and the webhook issued, this will reflect when the webhook was issued.
activity:
object Nested within the data object, contains the activity object along with associated keys. See Activities for more information.
user:
object Nested within the data object, contains an abbreviated form of the user object along with id, email, first_name, last_name and phone. See Users for more information.
lock:
object Nested within the data object, contains an abbreviated form of the lock object along with id, status and name. See Locks for more information.
      {
  "timestamp": 1422334455,
  "data": {
    "activity": {
      "id": "834745fb-f8ca-4179-be37-2f67112d2831",
      "kind": "lock-updated-locked",
      "status": "notice",
      "updated_kind": "lock-updated-locked",
      "updated_previous": "unlock",
      "updated_current": "lock"
    },
    "user": {
      "id": "6cd36428-1cdd-11e2-ba3b-4040401f6100",
      "email": "api_user@lockitron.com",
      "first_name": "",
      "last_name": "",
      "phone": null
    },
    "lock": {
      "id": "22c729b6-ae34-438e-8375-c32117f0f6a0",
      "status": "",
      "name": "Virtual Lockitron"
    }
  }
}
      
    

Errors & Messages

The Lockitron API has a standard format for errors and messages. When something goes wrong, it returns an error. When there is no object to display, it returns a message. Most errors return a 400 status code.

Format

status:
string Can either be: "success" or "error"
message:
string A human-readable message providing detail into what happened
reasons:
array An array of key/value pairs indicating issues with specific keys. The values are messages. The keys are where something went wrong.
      {
  status: "error",
  message: "The requested resource was not found.",
  reasons: [ ]
}
      
    

Locks

Lock refers to a Lockitron. You can use this resource to retrieve your locks and lock or unlock Lockitrons.

Properties

id:
string
name:
string, human-readable identifier for the Lockitron
next_wake:
ISO 8601 timestamp The next time a crowdfunded (WiFi-enabled) Lockitron is slated to wake up and process pending commands. This is null for non-crowdfunded Lockitrons.
last_heard_from:
ISO 8601 timestamp The last time a Lockitron checked in to Lockitron servers.
state:
string The state of the lock. It can be "lock", "unlock", or null.
button_type:
string The functionality of the lock. Certain Buzzer lockitrons can only be unlocked. This value is "unlock". The state of the new Lockitron is always known, the value is "slider". For older Lockitrons, the state is inconsistently known, it is "lock-unlock".
updated_at:
ISO 8601 timestamp The last time any value was updated on this lock.
handedness:
string The handedness of Lockitron (the state of the lock when the thumbturn is turned fully clockwise). It can be "unlocked", "locked", or null (unsupported).
avr_version:
string The AVR firmware version of a new Lockitron. It can be "true", "false", or null (unsupported).
battery_voltage:
string The battery voltage of a new Lockitron. It's typically between 3v and 8v, or null (unsupported).
sleep_period:
string The sleep interval for WiFi checkins on a crowdfunded (WiFi-enabled) Lockitron in seconds. Can be between 0 and 86400 or null.
avr_update_progress:
string The percentage completion of an update_avr_firmware event. 0-99 indicates the update is in progress, 100 indicates complete and -1 indicates error. This is null for non-crowdfunded Lockitrons.
ble_update_progress:
string The percentage completion of an update_ble_firmware event. 0-99 indicates the update is in progress, 100 indicates complete and -1 indicates error. This is null for non-crowdfunded Lockitrons.
serial_number:
string An identifier printed on the Lockitron, generally used in support.
hardware_id:
string An identifier advertised by the Lockitron (crowdfunded and Bolt) for Bluetooth operations.
connected:
string An indication whether or not the Lockitron is currently online. Can be "true", "false" or null. Used primarily to identify if Lockitron Bolt is accessible from the web via a Bridge unit (in which case the response will be true). If null (unsupported), you should assume the Lockitron is currently online.
time_zone:
string The default timezone for every date related to this lock. This includes the timezone for every Activity as well as start/expiration dates for keys. It's in Tz format
keys:
array The list of keys associated with this lock.
sms:
boolean Whether or not SMS access is turned on. You can enable/disable it in your Dashboard.
      
      
    

Retrieving All Locks

This endpont shows the locks the current user has access to, including the keys associated with the locks.

      GET https://api.lockitron.com/v2/locks
    
      GET https://api.lockitron.com/v2/locks
    


    

Retrieving a Specific Lock

This endpoint returns a specific Lock that the current user has access to and all the keys for that Lock visible to the current user.

      GET https://api.lockitron.com/v2/locks/:id
    
      GET https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0
    


    

Locking and Unlocking

This method will lock or unlock the user's door. It blocks until locking/unlocking is finished. If the Lockitron is asleep, it can take several minutes. Failures return standard errors.

Arguments

state:
string Possible states include:
"lock", "unlock", or "toggle"
noblock:
string Optional: whether or not the request will block - by default requests will block until the lock action completes. We recommend enabling noblock true for crowdfunded Lockitrons where latency can be minutes or hours.
"true" or "false"
      PUT https://api.lockitron.com/v2/locks/:id
    
      PUT https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0
    


    

Changing the name

Lockitrons have human-readable names. These are visible across all the apps to show the user which Lockitron they're currently using. This method lets you change it.

Arguments

name:
string
      PUT https://api.lockitron.com/v2/locks/:id
    
      PUT https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0
    


    

Changing the handedness

Crowdfunded (WiFi-enabled) Lockitrons have a specific handedness - whether they turn clockwise to lock or unlock. This impacts the reported state (locked or unlocked) of Lockitron.

Arguments

handedness:
string This may be set as locked or unlocked to indicate the state of the lock when the thumbturn when turned fully clockwise..
      PUT https://api.lockitron.com/v2/locks/:id
    
      PUT https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0
    


    

Changing the sleep interval

Set the sleep interval in seconds at which Lockitron connects to WiFi to check for pending commands. Warning: setting this below 1800 will significantly impact battery life.

Not supported for virtual or Access Lockitrons.

Arguments

sleep_period:
string Set as a value between 0 and 86400.
      PUT https://api.lockitron.com/v2/locks/:id
    
      PUT https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0
    


    

Updating the firmware

The crowdfunded Lockitrons can ben sent commands to update their firmware. This includes the AVR (primary) and BLE firmware. These methods initiate firmware updates but should be used with care.

AVR Update will take 2-5 minutes to complete after a unit wakes up. Lockitron will be unresponsive during this time and play a song once update is complete.

BLE Update will take 5-15 minutes to complete after a unit wakes up.

Not supported for virtual or Access Lockitrons.

Arguments

update_avr_firmware:
string Set to true to initiate AVR update (primary firmware).
update_ble_firmware:
string Set to true to initiate BLE update.
      PUT https://api.lockitron.com/v2/locks/:id
    
      PUT https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0
    


    

Keys

Keys represent a User's access to a Lock. They can start and expire. Admins and owners can invite users, modify keys, and revoke keys. Admins can only invite, modify, and revoke guests. Owners can invite, edit, and revoke anyone except themselves. Nobody can modify their own key.

Every valid key can lock and unlock a Lock.

Properties

id:
string
start_date:
ISO 8601 timestamp The time when the key starts. null indicates it starts at the time it the key was issued.
expiration_date:
ISO 8601 timestamp The time when the key expires. null means it never expires.
role:
string The role of the key. This can be owner, admin, or guest. owner can invite, edit, and revoke anyone except themselves. There is only one owner. admin can invite, edit, and revoke guest but not other admins, themself, or the owner. guest can only lock and unlock. There can be an unlimited number of admin and guest
valid:
boolean Denotes whether or not the key is valid. Keys may be invalid because they're pending, disabled, or expired.
visible:
boolean Denotes whether or not the key should be visible to the user. If it's active, it starts soon, or it recently expired, it should be visible to the user.
sms_pin:
string The four character pin code used for SMS access. This only applies to Locks with SMS access enabled. It may be present regardless.
user:
User, the User this key belongs to.
      
      
    

Retrieving Keys

This method returns all of the keys associated with a Lock

      GET https://api.lockitron.com/v2/locks/:lock_id/keys
    
      GET https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0/keys
    


    

Inviting Users

This method will find or create a new User and invite them to the Lockitron you specify in the :lock_id. This will give the User access to the Lockitron. It requires an email or phone. Optionally, you can set a role, start_date, expiration_date. For new users, you can set the name.

Sending an invitation to a User will notify them by email or phone. If the User you're inviting doesn't have an account, they will be emailed or texted an activation link. If they do have an account, they will be notified by email and/or phone.

Arguments

email:
string The email address of the User you wish to invite. This is required if phone is not present.
phone:
string The phone number of the User you wish to invite. Formatting will be stripped out (using the phones gem). Phone extensions will be stripped out too. This is required if email is not present.
name:
string The full name of the User you're inviting. This argument will be ignored if the User already exists.
start_date:
ISO 8601 timestamp The date when the key becomes usable.
expiration_date:
ISO 8601 timestamp The date when the key becomes unusable.
role:
string The role of the Key being invited. Can be: "guest" or "admin". Only owners can invite admins. The default is "guest"
      POST https://api.lockitron.com/v2/locks/:lock_id/keys
    
      POST https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0/keys
    


    

Modifying Keys

This method lets you modify pre-existing keys. It requires that the role of the Key the User is modifying is lower than the Key that was issued. This means that guests cannot modify admins or the owner and that admins cannot modify other admins.

Arguments

id:
string, the id of the Key being modified
start_date:
ISO 8601 timestamp
expiration_date:
ISO 8601 timestamp
role:
string
      PUT https://api.lockitron.com/v2/locks/:lock_id/keys/:id
    
      PUT https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0/keys/731cca57-b951-4a57-99b1-1cd1b8d46059
    


    

Revoking Keys

Just as you can invite a User and modify a Key, you can also revoke the Key. Only admins and the owner can revoke keys. Admins can only revoke guests. Nobody can revoke their own key.

      DELETE https://api.lockitron.com/v2/locks/:lock_id/keys/:id
    
      DELETE https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0/keys/731cca57-b951-4a57-99b1-1cd1b8d46059
    
{
  status: "success",
  message: "You have successfully deleted that key.",
  reasons: [ ]
}

    

Users

A User is a person using Lockitron. Users have many keys, locks, and activities.

Properties

id:
string
email:
string, the email address associated with the User
phone:
string, the phone number associated with the User
full_name:
string, the full name of the User
first_name:
string, the first name of the User
last_name:
string, the last name of the User
activated:
boolean Indicates whether or not the user has activated their account
      
      
    

Retrieving a User

This method lets you retrieve a User by ID. It will only return users that are associated with a Lock that the current user has access to.

Arguments

face:
string Adding this argument will redirect you to a JPEG or PNG image of the User's face. The possible values are: "thumbnail" (160x160), "header" (120x120), and "big" (400x400).
      GET https://api.lockitron.com/v2/users/:id
    
      GET https://api.lockitron.com/v2/users/6cd36428-1cdd-11e2-ba3b-4040401f6100
    


    

Retrieving The Current User

It can be a pain to keep track of the User the access_token belongs to. This method makes that easier. It returns the current user associated with the provided access_token.

Arguments

face:
string Adding this argument will redirect you to a JPEG or PNG image of the User's face. The possible values are: "thumbnail" (160x160), "header" (120x120), and "big" (400x400).
      GET https://api.lockitron.com/v2/users/me
    
      GET https://api.lockitron.com/v2/users/me
    


    

Activities

Activities are logs of recent actions on a particular lock or key.

Properties

id:
string
created_at:
ISO 8601 timestamp, when the Activity was performed
status:
string The severity of the Activity. Could be: "warning", "error", "success", "notice".
kind:
string, kind of Activity
updated_value:
string Indicates the change in the Lock or Key.
user
User, The User associated with the Activity
      
      
    

Retrieving Activities

This method allows you to retrieve the last 10 activities on a Lock. Some examples of activities include: a User locking their Lock, a User being invited the a Lock, or a Key being revoked.

It only shows activities that the current user's key has access to. If they're a guest, they can only see activities of their own. Admins and owners can see everyone's activity.

      GET https://api.lockitron.com/v2/locks/:lock_id/activity
    
      GET https://api.lockitron.com/v2/locks/22c729b6-ae34-438e-8375-c32117f0f6a0/activity
    


    

Cancel a Pending Action

This method allows you to cancel a pending activity on a Lock. Pending acitivities are those activities on crowdfunded (WiFi-enabled) Lockitrons which have yet to be carried out because the Lockitron has not yet reconnected to WiFi since the command was sent.

Arguments

activity_id:
string This is the activity_id you wish to cancel. The last pending_activity can be found on the Lock object..
      DELETE https://api.lockitron.com/v2/locks/:lock_id/activity/:id
    
{
  status: "success",
  message: "You have successfully cancelled this pending request.",
  reasons: [ ]
}

    

Kinds of Activities

There are many different kinds of Activity. Sometimes it's a User unlocking their door when they get home. Other times it's a User revoking someone else's access to their Lock. Below, the different kinds are enumerated:

Kinds

setup:
The Lock was setup
low-battery:
The Lock is running low on battery.
wifi-disconnected:
The Lock's wifi was disconnected.
unauthorized:
An unauthorized User attempted to lock or unlock the Lock.
lock-offline:
The Lock went offline.
lock-jammed:
The Lock has jammed.
lock-transmitter-unplugged:
The Lock's USB transmitter was unplugged. This only applies to older Lockitrons and the Lockitron Buzzer.
lock-updated-lock:
The Lock was locked.
lock-updated-unlock:
The Lock was unlocked.
lock-updated-owner:
The owner of the Lock was changed.
key-created:
A User was invited to this Lock.
key-revoked:
A Key was revoked from this Lock
key-updated-start:
The Key's start_date changed.
key-updated-expiration:
The Key's expiration_date changed.

key-updated-role:
The Key's role changed. This only applies to admin and guest