Introduction

Attention: LockState’s v1 API is currently in Beta.

LockState makes periodic changes to improve the performance of our API, as well as adding new functionality. LockState will notify registered API users of updates requiring changes.

This document contains all necessary resources to consume the LockState RESTful API, meaning that a client application is able authenticate a user, fetch, create, update, delete and perform other actions via HTTP with objects in JSON representation.

Production environment

• OAuth base URL: https://connect.remotelock.com
• API base URL: https://api.remotelock.com

Changelog

• 2018-08-13
  • Added battery_replaced event type for Lock.
• 2018-04-12
  • Added a signal_quality attribute to Lock, PowerPlug, Thermostat.
  • Deprecated wifi_level attribute on Lock, PowerPlug, Thermostat.
• 2017-09-19
  • Added a generate_pin attribute when creating and updating access persons. Its default value is false and when true is passed, a random PIN is generated for that access person.
• 2017-07-27

  • Add requirements and recommendations for webhook endpoint handler.

    See Notification Subscriber > Create a webhook notification subscriber section.

    The new requirements will be enforced as of August 14, 2017.

• 2017-07-18

  • Add status attribute to access_guest and access_user types.

    Statuses for access_guest type:

    • upcoming - initial status when start time has not met yet
    • current - initial status when start time has already met
    • expired - when end time has already met
    • deactivated - when a user manually deactivates it. See new endpoint below

    
    Statuses for access_user type:

    • current - initial status
    • deactivated - when a user manually deactivates it. See new endpoint below

    
    

  • Add PUT /access_persons/:id/deactivate endpoint to deactivate access person on associated devices and keep the record on history. We recommend using this new endpoint rather than DELETE /access_persons/:id because you can fetch past access persons using the filter explained below.

    The current behavior of DELETE /access_persons/:id was preserved: once it deletes, the access person cannot be fetched via API or UI anymore.

  • Add ability to filter access persons by status(es). Example:

    GET /access_persons?attributes[status][]=deactivated&attributes[status][]=expired

  • When status filter is not provided to GET /access_persons, the current behavior was preserved: it only retrieves upcoming and current statuses.

• 2017-06-20
  • Remove record_type, record_id, to_type and to_id attributes from PUT /common_doors/:id endpoint.
• 2017-05-24
  • Remove ACS instructions and all the remaining ACS controller endpoints.
• 2017-03-14
  • remove Access Instructions, Device Permissions, Guest Email Templates, Roles, User Roles, User Invitations
• 2017-02-27
  • Add event examples for new event types: access_person_synced_event, access_person_sync_failed_event and access_guest_late_sync_event
• 2017-02-23
  • Add the following fields to access_person_access API type:
    • devices_count
    • devices_synced_count
    • devices_failed_sync_count
    • devices_pending_sync_count
• 2017-02-20
  • Add email preview/resend capability to Resort Lock Guests
• 2017-02-07
  • remove generated_pin_digits attribute from the Account
  • removed all attributes from ACS doors except name, state, lock_action_schedule_id and location_id
• 2017-01-26
  • change wake_wifi parameter options
  • add LS-5i only wake_wifi option user_action_except_manual
• 2016-12-19
  • Remove all billing endpoints.
• 2016-12-06
  • Deprecate all ACS endpoints except ACS doors.
  • Devices endpoint returns ACS doors instead of ACS readers.
  • Multiple endpoints now accept or are related to ACS doors instead of ACS readers: events, notifications, device permissions, door groups, notification subscriptions, access person accesses and common doors.
  • All the existing objects that used ‘acs_reader’ type are now migrated to ‘acs_door’ (ID stays the same).
• 2016-11-23
  • Added Common Doors functionality
• 2016-11-18
  • wifi_level_changed event is now connectivity
  • power_level_changed event is now power_level_low
• 2016-11-15
  • Guest emails are no longer automatically sent (with the exception of integrations). You must explicitly send the email via: POST /access_persons/:id/email/notify
• 2016-11-02
  • Local PINs support for 5i/6i/7i.
• 2016-11-01
  • Resort Lock Guests only support hours. Please see parameters.
  • Delivery of Access Denied and Locked notifications.

Authentication

RemoteLock uses OAuth 2.0 to authenticate users in applications installed in mobile devices or running in external servers. The supported OAuth flows:

• Authorization Code Grant - RFC 6749-Section 4.1

  The RemoteLock user credentials are only accepted in RemoteLock sign in page, which generates an Authorization Code for an access token request.

  The access token for this flow gives access to the user resources that signed in using your Application.

• Client Credentials Grant - RFC 6749-Section 4.4

  Only the Application ID and Secret are used to authorize access to the API.

  The access token for this flow only allows access to resources associated with the application’s account.

Once a user is authorized, every API request must include a valid access token.

Before proceeding: pick the OAuth flow that is suitable for your business and skip the flows that do not apply to your account in this guide.

The following OAuth 2.0 endpoints are available under https://connect.remotelock.com/. These are needed for OAuth2 client library you’ll be using:

    GET       /oauth/authorize
    POST      /oauth/token

Choose an OAuth2 client library for your language

To simplify integration with RemoteLock it is strongly recommended to use one of the open source OAuth2 client libraries available in your language. The library will handle many details described in this documentation.

Since OAuth2 is an open protocol a quick Google search will give you at least a couple options. Here are some examples:

• iOS: https://github.com/OAuthSwift/OAuthSwift
• Android: https://github.com/wuman/android-oauth-client
• Ruby: https://github.com/intridea/oauth2

Setup a new Application

1. Send an email to sales@lockstate.com requesting API Access for your account.
2. Once API access is enabled for your account, go to the developer portal and sign in to manage your OAuth Applications.

1. Authorization Code Grant - RFC 6749-Section 4.1

1.1. Generating the initial Authorization Code

Whenever you need access to a user’s account for the first time, the application should load the Authorize URL in a browser or webview. The user will enter the credentials and the server will redirect to the Callback URL so that the application can extract the authorization code and then generate an access token.

Example:

Let your Application settings be:

Application ID: abc
Secret: xyz
Callback URL: http://your.server/oauth_callback

The Authorize URL should be:

https://connect.remotelock.com/oauth/authorize?client_id=a1b2c3&response_type=code&redirect_uri=http://your.server/oauth_callback

Your app should load the above URL in a browser and the user will enter credentials on it. Once the authentication succeeds, the server will redirect the request to:

http://your.server/oauth_callback?code=123

where 123 is the Authorization Code that is valid for 10 minutes, which is enough time to your application request the token for the first time. Your application must be able to handle this URL in order to capture this code so that it can obtain the OAuth Token.

1.2. Generating an OAuth Token

• Make the following POST request to obtain Access and Refresh tokens:

  POST /oauth/token
  Host: connect.remotelock.com
  Content-Type: application/x-www-form-urlencoded
  
  code=123&
  client_id=abc&
  client_secret=xyz&
  redirect_uri=http://your.server/oauth_callback&
  grant_type=authorization_code
  

• The response will be a JSON such as:

  {
    "access_token": "1/4cc3ss-t0k3n",
    "expires_in": 7200,
    "token_type": "Bearer",
    "refresh_token": "1/r3fR3sH-t0k3n"
  }
  

1.3. Refresh Token

Each access token expires in 7200 seconds (2 hours). The access token JSON response contains a refresh_token that can be used to issue a new access_token without asking for user authentication again.

• In order to get a new access token, make the following POST request:

  POST /oauth/token
  Host: connect.remotelock.com
  Content-Type: application/x-www-form-urlencoded
  
  client_id=abc&
  client_secret=123&
  refresh_token=1/r3fR3sH-t0k3n&
  grant_type=refresh_token
  

• The response will be a JSON such as:

  {
    "access_token": "1/N3w-4cc3ss-T0k3n",
    "expires_in": 7200,
    "refresh_token": "1/n3w-r3fR3sH-t0k3n"
    "token_type": "Bearer"
  }
  

Your application should store both Access Token and Refresh Token so that it can access the user account when the user is offline or the application is running in background.

Whenever an Access Token expires and you use the Refresh Token to request a new Access Token, the response includes a new Refresh Token, meaning the previous one became invalid, and then your application should store the new Access Token and Refresh Token replacing the previous (expired) ones.

Here is an example of this flow:

1. Customer authorizes and you get the initial Access Token A as well as a Refresh Token X
2. You access customer data using Access Token A
3. After 2 hours the Access Token A expires, but you need to access customer data and you notice that Access Token A is expired
4. You make a request to issue a new Access Token based on the Refresh Token X and you get a new Access Token B and a new Refresh Token Y. At this point, the Refresh Token X becomes invalid since it was just used
5. Repeat from step 2 replacing A with B and X with Y

The user can revoke the authorization to your app at anytime, so the Refresh Token will become invalid and your app will need to ask for user authorization again.

2. Client Credentials Grant - RFC 6749-Section 4.4

In this flow, only your account resources are available via API. For this reason, the only credentials required are the Application ID and Secret.

Let your Application settings be:

Application ID: abc
Secret: xyz

2.1. Generating an OAuth Token

• Make the following POST request to obtain Access and Refresh tokens:

  POST /oauth/token
  Host: connect.remotelock.com
  Content-Type: application/x-www-form-urlencoded
  
  client_id=abc&
  client_secret=xyz&
  grant_type=client_credentials
  

• The response will be a JSON such as:

  {
    "access_token": "1/4cc3ss-t0k3n",
    "expires_in": 7200,
    "token_type": "Bearer",
  }
  

Notice that this flow does not include a Refresh Token, meaning that this same request must be done when the access token expires.

Making requests with an OAuth Token

Just make a GET request using a valid access token. Example:

GET /locations
Host: api.remotelock.com
Accept: application/vnd.lockstate.v1+json
Authorization: Bearer 1/4cc3ss-t0k3n

Revoking an OAuth Access Token

Send the following POST request to immediately revoke a token:

POST /oauth/revoke
Host: connect.remotelock.com
Content-Type: application/x-www-form-urlencoded

client_id=abc&
client_secret=xyz&
token=1/4cc3ss-t0k3n

JSON Structure Overview

JSON request structure

The HTTP methods POST/PUT/PATCH require the header Content-Type: application/json and the request body must contain a valid JSON structure.

Other HTTP methods accept empty or missing Content-Type header since the request body is ignored.

Example JSON request structure:

• POST https://api.remotelock.com/articles/3/comments

  {
    "attributes": {
      "body": "Very informative article"
    }
  }
  

JSON response structure

• All responses have data root key. data object keys are id, type, attributes and links (optional).
• meta top level key is used for collection pagination.
• Relationship resource URLs can be fetched from the links key. A self URL is also included.
• “1-to-1” relationship object ids are included in the attributes object. Example: "author_id": 1 for the author relationship.
• All date and time fields are using ISO 8601 format.

JSON response structure for a collection

• GET https://api.remotelock.com/articles

  {
    "data": [
      {
        "type": "article",
        "id": "3",
        "attributes": {
          "title": "JSON API paints my bikeshed!",
          "body": "The shortest article. Ever.",
          "author_id": 1,
          "created_at": "2015-07-23T18:51:11Z",
          "updated_at": "2015-07-23T18:51:11Z"
        },
        "links": {
          "self": "https://api.remotelock.com/articles/3",
          "author": "https://api.remotelock.com/authors/1",
          "comments": "https://api.remotelock.com/comments"
        }
      },
      {
        "type": "article",
        "id": "5",
        "attributes": {
          "title": "Ruby on Rails framework",
          "body": "RoR is 10 years old!",
          "author_id": 1,
          "created_at": "2015-05-22T14:56:29Z",
          "updated_at": "2015-05-22T14:56:28Z"
        },
        "links": {
          "self": "https://api.remotelock.com/articles/3",
          "author": "https://api.remotelock.com/authors/1",
          "comments": "https://api.remotelock.com/comments"
        }
      }
    ],
    "meta": {
      "page": 1,
      "per_page": 2,
      "total_pages": 7,
      "total_count": 14
    }
  }
  

JSON response structure for a single resource

• GET https://api.remotelock.com/articles/3

  {
    "data": {
      "type": "article",
      "id": "3",
      "attributes": {
        "title": "JSON API paints my bikeshed!",
        "body": "The shortest article. Ever.",
        "author_id": 1,
        "created_at": "2015-07-23T18:51:11Z",
        "updated_at": "2015-07-23T18:51:11Z"
      },
      "links": {
        "self": "https://api.remotelock.com/articles/3",
        "author": "https://api.remotelock.com/authors/1",
        "comments": "https://api.remotelock.com/comments"
      }
    }
  }
  

Errors

There are 2 types of error responses:

• resource errors
• general errors

Resource errors

Resource errors are used to indicate an error happened for a resource you’re trying to work with. For example: if an invalid configuration option is passed when updating a lock, the response will be a resource error.

Here’s the example response when an error happens:

{
  "attributes": {
    "name": "",
    "age": 10
  },
  "errors": [{
    "attribute": "name",
    "messages": ["is empty"],
    "full_messages": ["name is empty"]
  }]
}

In case an error is not related to a particular attribute, the errors attribute value will be null.

{
  "attributes": {
    "name": "",
    "age": 10
  },
  "errors": [{
    "attribute": null,
    "messages": ["Subuser creation limit reached, please upgrade your account."],
    "full_messages": ["Subuser creation limit reached, please upgrade your account."]
  }]
}

General errors

General errors are used to describe application-wide errors. For example: the response contains general error if you try creating a lock but the account doesn’t have a paid subscription.

Here’s the example response:

{
  "message": "Please create a subscription",
  "type": "billing_subscription_required"
}

Pagination

Collection resources can be paginated using the data from meta top level key.

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 2,
    "total_pages": 7,
    "total_count": 14
  }
}

On every endpoint that responds with a collection of resources, you can provide the following query parameters:

• page (Default: 1, Minimum: 1, Maximum: value of total_pages from meta)
• per_page (Default: 25, Mimimum: 1, Maximum: 50)

The pagination is limited to access up to 10,000 resources, which means the product page * per_page should not exceed that number.

Examples:

• /devices?page=5 retrieves the 5th page of devices
• /devices?per_page=40 retrieves the first 40 devices
• /devices?per_page=50&page=2 retrieves devices from 51 to 100

Filtering

Filter results by multiple ids

Supported in endpoints that return a collection of resources

• Query format: ?id[]=<id 1>&id[]=<id 2>&...

  Example: To retrieve devices with ids a1b2 and c3d4:

  GET https://api.remotelock.com/devices?id[]=a1b2&id[]=c3d4

Filter results by resource type

Supported in endpoints that return a collection of resources of multiple types

• Query format for a single type: ?type=<type>

  Example: To retrieve devices of a single type, lock:

  GET https://api.remotelock.com/devices?type=lock

• Query format for multiple type: ?type[]=<type 1>&type[]=<type 2>&...

  Example: To retrieve devices of types power_plug and camera:

  GET https://api.remotelock.com/devices?type[]=camera&type[]=power_plug

Filter results by association

Used to apply the id or type filter in a resource association

Example: To retrieve devices of the location a1b2

GET https://api.remotelock.com/devices?attributes[location_id]=a1b2

Sorting

Most endpoints that return a collection are sortable. Additionally, these endpoints usually have a default sort attribute. The documentation for each endpoint specifies the default sort attribute as well as other attributes that can be used for sorting (if any).

Query formats

• using single sort attribute: ?sort=<attr>
• using multiple sort attributes: ?sort[]=<attr 1>&sort[]=<attr 2>&...

Sort order

The default sort order for any attribute is “ascending”. In order to get “descending” sort order prefix the attribute with hyphen (-).

Examples:

• “ascending” sort order: ?sort=name
• “descending” sort order with hyphen: ?sort=-name

Examples:

• Retrieve devices sorted “ascending” by name attribute:

  GET https://api.remotelock.com/devices?sort=name

• Retrieve devices sorted “descending” by name attribute:

  GET https://api.remotelock.com/devices?sort=-name

• Retrieve devices sorted “ascending” by created_at and “descending” by name:

  GET https://api.remotelock.com/devices?sort[]=created_at&sort[]=-name

API versioning

Specifying API version

It is strongly recommended to explicitly specify the version. Specifying the version can be done:

• in the resource url

    https://api.remotelock.com/v1/articles/1
  

• or via request Accept header

    Accept: application/vnd.lockstate+json; version=1
  

If API version is not specified, the application will default to the latest version.

Changes

API version will increase only if there’s a breaking change.

For example: if a single field is added to the resource, the version won’t change as this is a non breaking change.

Rate Limiting

Currently, each account is limited to 120 requests/minute.

Each API response includes rate limiting related headers such as:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1452626187

Whenever the account has exceeded the rate limit, the request will be responded with status 429 (Too Many Requests) and the body will contain following JSON:

{
  message: "Your account has exceeded the rate limit. Check the X-RateLimit-* headers."
}