August Lock REST APIs (the basics)

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.2
Request 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 /users
POST /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}/pin
DELETE /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}/mailinglist
DELETE /cameras/{cameraID}
POST /unverifiedusers
PUT /unverifiedusers/{userID}
GET /augustappversionok/android/{appversion}
PUT /private/locks/status/{lockID}
POST /apns/devtoken

Written by

Making and breaking things for most of my life. Tw: @nolanbrown IG: @nolan

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store