Open in app

Sign in

Write

Sign in

Home

Library

Stories

Stats

August Lock REST APIs (the basics)

Nolan Brown

--

I promised to write up documentation for August Lock’s REST APIs after writing The Process of Reverse Engineering the August Lock API. It took me way too long to get it done; a new job, a 5 year old and a baby on the way will do that sometimes. Hopefully the documentation below is helpful to some people but it does require an August Lock and August Connect.

I’ve listed additional endpoints I’m aware of but haven’t had a chance to explore at the bottom of this article.

Login and retrieve access token

POST https://api-production.august.com/session

Request Headers:x-august-api-key: 727dba56-fe45–498d-b4aa-293f96aae0e5
x-kease-api-key: 727dba56-fe45–498d-b4aa-293f96aae0e5
Content-Type: application/json
Accept-Version: 0.0.1
User-Agent: August/Luna-3.2.2Request Body: (JSON Encoded)
{
  "installId": <Random UUID>,
  "password": "XXXXXXXX",
  "identifier": "phone:+15555551234"
}

Response:

Response Headers:
x-august-access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.<Base 64 encoded JWT>Response Body:
{
  "installId": "0000000-0000-0000-0000-000000000000",
  "applicationId": "",
  "userId": "0000000-0000-0000-0000-000000000000",
  "vInstallId": true,
  "vPassword": true,
  "vEmail": false,
  "vPhone": false,
  "hasInstallId": true,
  "hasPassword": true,
  "hasEmail": true,
  "hasPhone": true,
  "isLockedOut": false,
  "captcha": "",
  "email": [
    "email:myemail@gmail.com"
  ],
  "phone": [
    "phone:+15555551234"
  ],
  "expiresAt": "2016-06-03T08:39:48.377Z",
  "LastName": "Brown",
  "FirstName": "Nolan"
}

Get Houses

GET https://api-production.august.com/users/houses/mine

Note the addition of the x-august-access-token retrieved from the initial login response.

Request Headers:x-august-api-key: 727dba56-fe45–498d-b4aa-293f96aae0e5
x-kease-api-key: 727dba56-fe45–498d-b4aa-293f96aae0e5
Content-Type: application/json
Accept-Version: 0.0.1
User-Agent: August/Luna-3.2.2
x-august-access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.<Base 64 encoded JWT>Response Body:
[
  {
    "HouseID": "0000000-0000-0000-0000-000000000000",
    "HouseName": "A House",
    "type": "superuser",
    "imageInfo": {
      "public_id": "kfajdrqepoldjqamadfa",
      "version": 134543552,
      "signature": "o2IPnOkrLUaIIFg5YAMPo2IPnOkrLUaIIFg5YAMP",
      "width": 1333,
      "height": 375,
      "format": "png",
      "resource_type": "image",
      "created_at": "2017-01-09T20:42:23Z",
      "bytes": 544234,
      "type": "upload",
      "etag": "e3b9f789d1f835e8ff9d4656c7eafc23",
      "url": "http:\/\/res.cloudinary.com\/august-com\/image\/upload\/v3254355454\/kfajdrqepoldjqamadfa.png",
      "secure_url": "https:\/\/res.cloudinary.com\/august-com\/image\/upload\/v3254355454\/kfajdrqepoldjqamadfa.png"
    }
  },
  {
    "HouseID": "0000000-0000-0000-0000-000000000000",
    "HouseName": "A House",
    "type": "superuser",
    "imageInfo": {
      "public_id": "kfajdrqepoldjqamadfa",
      "version": 134543552,
      "signature": "o2IPnOkrLUaIIFg5YAMPo2IPnOkrLUaIIFg5YAMP",
      "width": 1333,
      "height": 375,
      "format": "png",
      "resource_type": "image",
      "created_at": "2017-01-09T20:42:23Z",
      "bytes": 544234,
      "type": "upload",
      "etag": "e3b9f789d1f835e8ff9d4656c7eafc23",
      "url": "http:\/\/res.cloudinary.com\/august-com\/image\/upload\/v3254355454\/kfajdrqepoldjqamadfa.png",
      "secure_url": "https:\/\/res.cloudinary.com\/august-com\/image\/upload\/v3254355454\/kfajdrqepoldjqamadfa.png"
    },
    "nestEnabled": {
      "StructureID": "01v_wtkm56Ld9nARrnyuAEPucYGrHQ7QW0OoaMwS1plrq",
      "StructureName": "Wayward"
    }
  }
]

Get Locks

GET https://api-production.august.com/users/locks/mine

Request Headers:x-august-api-key: 727dba56-fe45–498d-b4aa-293f96aae0e5
x-kease-api-key: 727dba56-fe45–498d-b4aa-293f96aae0e5
Content-Type: application/json
Accept-Version: 0.0.1
User-Agent: August/Luna-3.2.2
x-august-access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.<Base 64 encoded JWT>
Response Body:
{
  "A6697750D607098BAE8D6BAA11EF8063": {
    "LockName": "Front Door",
    "UserType": "superuser",
    "macAddress": "2E:BA:C4:14:3F:09",
    "HouseID": "0000000-0000-0000-0000-000000000000",
    "HouseName": "A House"
  }
}

A6697750D607098BAE8D6BAA11EF8063 is your lock ID

Get Lock Status

PUT https://api-production.august.com/remoteoperate/<LOCKID>/status

Request Headers:x-august-api-key: 727dba56-fe45–498d-b4aa-293f96aae0e5
x-kease-api-key: 727dba56-fe45–498d-b4aa-293f96aae0e5
Content-Type: application/json
Accept-Version: 0.0.1
User-Agent: August/Luna-3.2.2
x-august-access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.<Base 64 encoded JWT>Response Body:{
  "status": "kAugLockState_Locked"
}

Unlock your August Lock

PUT https://api-production.august.com/remoteoperate/<LOCKID>/unlock

Response Body:{
  "status": "kAugLockState_Locked"
}

Lock your August Lock

PUT https://api-production.august.com/remoteoperate/<LOCKID>/unlock

Request Headers:x-august-api-key: 727dba56-fe45–498d-b4aa-293f96aae0e5
x-kease-api-key: 727dba56-fe45–498d-b4aa-293f96aae0e5
Content-Type: application/json
Accept-Version: 0.0.1
User-Agent: August/Luna-3.2.2
x-august-access-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.<Base 64 encoded JWT>Response Body:{
  "status": "kAugLockState_Unlocked"
}

Unexplored Endpoints

Users

POST /users
POST /users/{userID}/image
GET /users
GET /users/me
GET /users/me/legal
PUT /users/me/legal
GET /users/houses/mine
GET /users/{userID}
GET /users/locks/mine
GET /users/cameras/mine
PUT /usersPOST /validate/email
POST /validate/phone

Keypads

GET /keypads/firmware/{keypadID}/{version}
GET /keypads/{keypadID}
GET /keypads/{keypadID}/{lockID}/offlinekey
GET /keypads/{keypadID}/firmware/{version}
GET /keypads/{keypadID}/code
PUT /keypads/{keypadID}/code
POST /keypads
DELETE /keypads/{keypadID}

Bridges

GET /bridges/{bridgeId}
GET /bridges/{bridgeID}/notifications
POST /bridges/{bridgeID}/notifications/system
POST /bridges
DELETE /bridges/{bridgeID}/notifications/system
DELETE /bridges/{bridgeId}

Houes

GET /houses/{houseId}/guestbookentries/count
GET /houses/{houseId}/guestbookentries/{count}/{offset}
GET /houses/{houseID}
GET /houses/{houseID}/temperature
GET /houses/{houseID}/nestawaystatus
PUT /houses/{houseID}
PUT /houses/{houseID}/neststructure/{structureID}
PUT /houses/{houseID}/nestawaystatus/{status}
PUT /houses/{houseID}/image
POST /houses/{houseID}/guestbook
POST /houses
DELETE /houses/{houseID}/neststructure/{structureID}

Locks

POST /locks/setnotification/{lockID}/{otherUserID}/{when}
POST /locks/cameras/{lockID}/{cameraID}
POST /locks/log/{lockID}/lockdata
POST /locks/{houseID}GET /locks/{lockID}/firmware/{chip}/{version}
GET /locks/{lockID}/firmware/{version}
GET /locks/{lockID}
GET /locks/{lockID}/pins
GET /locks/log/before/{lockID}/{dateTime}/{count}
GET /locks/notifications/{lockID}/{otherUserID}
GET /locks/rules/{lockID}
PUT /locks/getlockrands/{lockID}PUT /locks/{lockID}
PUT /locks/adduser/{lockID}/{otherUserId}/{type}
PUT /locks/usage/{lockID}
PUT /locks/{lockID}/firmware/keypadchec
PUT /locks/timeadustment/{lockID}/{oldTimestamp}/{newTimestamp}
PUT /locks/{lockID}/offlinekeys/{action}
PUT /locks/acknowledgeparamupdate/{lockID}
PUT /locks/initiatecomm/{lockID}
PUT /locks/{lockID}/users/{userID}/pinDELETE /locks/{lockID}
DELETE /locks/{lockID}/pins
DELETE /locks/cameras/{lockID}/{cameraID}

Rules

PUT /rules/{ruleID}/{userID}
POST /rules/{lockID}
POST /rules/rulewithuser/{lockID}/{userID}
DELETE /rules/{ruleID}/{userID}
DELETE /rules/{ruleID}

Nest

PUT /nest/authtoken/deleted
POST /nest/camera
GET /nest/cameras
GET /nest/structures
PUT /nest/authtoken/{token}

Airbnb

GET /airbnb/listings
PUT /airbnb/listings/{listingID}/locks/{lockID}
POST /airbnb/authtoken
DELETE /airbnb
DELETE /airbnb/listings/{listingID}/locks/{lockID}

Misc

GET /apps/mine
DELETE /apps/{appID}GET /appfeatures/android/{version}GET /partners
POST /partners/{partnerID}/mailinglistDELETE /cameras/{cameraID}
POST /unverifiedusers
PUT /unverifiedusers/{userID}
GET /augustappversionok/android/{appversion}
PUT /private/locks/status/{lockID}
POST /apns/devtoken
API
Reverse Engineering
Smart Home
Rest Api

--

--

Responses (16)

Write a response

What are your thoughts?

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams