August Smart Lock

Cloud REST integration for August- and Yale-branded smart locks. Supports the August Wi-Fi Smart Lock (4th gen), the August Smart Lock Pro with August Connect bridge, the Yale Assure family with the August module, and the newer Yale Approach line that has migrated to the shared Yale Home cloud.

What's controlled

• Remote lock and unlock
• get_status — current locked/unlocked state of one lock
• get_locks — list locks visible to the account
• get_lock_detail — full cloud payload (battery, firmware, door-sense, last action)
• Status polling — the driver refreshes each zone's state attribute on an interval (default 60s)

Battery level is mirrored to the zone as battery_level (0–100) when the lock reports it.

Prerequisites

• A working August (or Yale Home) account with the lock already paired in the mobile app and reachable via a Connect bridge or built-in Wi-Fi. Cloud commands cannot reach a Bluetooth-only lock with no internet path.
• A long-lived access token for the account. The August cloud requires SMS or email 2FA to mint a token, and August does not publish an OAuth flow — so the token is bootstrapped externally (see below) and pasted into the GEM device row.
• A stable install_id UUID. Reuse the same UUID for every request from this GEM install. If you regenerate the UUID, you must re-run the 2FA flow.

Bootstrapping an access token

This is done once, outside GEM. The three-step flow (paraphrased from public community projects such as pyaugustapi, gtoken, and yalexs):

1. Generate a UUID v4 — this is your install_id.
2. POST /session with the install_id and your account email/phone — the server returns a session token (not yet validated).
3. POST /validation/phone (or /validation/email) — the cloud sends a 6-digit code.
4. POST /validate/phone with the code — the response contains the long-lived access token in the x-august-access-token response header.

Tools like gtoken script this end-to-end. Paste the resulting access_token (and the same install_id) into the GEM device.

Setup

1. Mint the access_token and install_id as above.
2. Add a device with driver august_smart_lock.
3. Set access_token and install_id. Leave api_base on the default unless your account has migrated to Yale Home — in that case, use https://api.aaecosystem.com.
4. Run get_locks on the device to list the lock UUIDs.
5. Create one zone per lock; set zone.address to the August lockID UUID.

Attributes

Device — required

Attribute	Type	Description
access_token	secure string	Bearer token from the 2FA bootstrap flow.
install_id	string	UUID v4. Must match the install_id used to mint the access_token.

Device — optional

Attribute	Type	Default	Description
api_base	string	https://api-production.august.com	Cloud endpoint. Use https://api.aaecosystem.com for Yale Home migrated accounts.
api_key	secure string	well-known mobile-client value	The x-august-api-key header value. Only override if you have a private value.
status_interval	int	60000	Status poll interval in ms. Minimum 15000 — the cloud rate-limits aggressive pollers.
request_timeout	int	15000	HTTP request timeout in ms.

Zones

One zone per lock. zone.address is the August lockID UUID. The driver writes:

• state — locked or unlocked
• battery_level — integer 0–100, when the lock reports it

A status the cloud reports as jammed or unknown is not written as either state — the zone keeps its last known state until the lock reports locked or unlocked again. An unlatched lock is reported as unlocked.

Zone address format

The August lockID as returned by get_locks (32 hex characters, no dashes). Example shape: ABCDEF1234567890ABCDEF1234567890.

Known limitations

• No push or WebSocket state. August does not expose a stable real-time event channel for third parties — the driver polls. Latency between a manual unlock at the lock face and the cloud reflecting it depends on the Connect bridge being awake.
• No PIN code management. The August /locks/{id}/pins/* endpoints exist but are not wired in this driver. Use the August app to manage codes for now.
• No history / activity feed. GET /locks/{id}/activity returns a rich event log; not yet exposed here.
• No token renewal. A revoked token returns 401 and the device is marked disconnected; admins must paste a fresh token in. There is no silent re-bootstrap path because that would require interactive 2FA. If the cloud is unreachable or refuses the token at connect, the driver re-tries the lock list after 30 seconds, doubling up to every 5 minutes, so a site that boots during an internet outage (or just after a token was minted) recovers on its own. Status polling likewise slows down, doubling up to 5 minutes, after three passes in which every lock failed, and returns to status_interval as soon as the cloud answers.
• A failed command is reported as an error. lock / unlock return an error for any non-2xx reply, a timeout, or a web page in place of the August API (a captive portal or proxy). Commands are never re-sent automatically. A timed-out command may still have reached the lock — check its state before sending it again.

Troubleshooting

Symptom	Check
401 on every request	Token revoked or install_id changed. Re-run the bootstrap flow with the same install_id.
get_locks returns an empty object	The account has no paired locks, or the account migrated to Yale Home — switch api_base to https://api.aaecosystem.com.
lock / unlock returns 422	The lock has no internet path. Confirm the Connect bridge is online (or the lock has Wi-Fi).
State never updates after a manual unlock	Confirm the bridge is online in the August app. The cloud only reflects local actions when the bridge sees them.
Status polling is slow	Cloud rate limits make sub-30s polling unreliable. 60s is the recommended floor.

See also

• genie_aladdin_connect — sibling cloud-REST driver for residential garage controllers.
• seamapi — Seam's multi-vendor lock cloud, which fronts August/Yale among others; an alternative if the integrator already pays for Seam.