August Lock REST APIs (the basics)

Nolan Brown
Apr 18, 2017 · 3 min read

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

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade