English
Lock APIs: how their versions pile up, and why you have to handle them all at once
Why does a lock maker's API change, and why do its old versions remain the integrator's problem?
A lock maker's API can change for at least three reasons, and its old versions do not disappear when a new one is published. It changes because some devices bring capabilities it had no way to describe, because security rules get tightened, or maybe because the maker's business rules or platform change. Each time, the old version of the API stays in service for some of the maker's customers, so to keep working whatever you had working, you end up having to support every version at once.
What you are reading is one facet among many of what we at Seam call "manufacturer API hell," which we handle on our customers' behalf. Other articles in this section show more examples.
The API changes when what devices do, or what kinds of devices exist, changes
Nuki publishes several APIs for the same lock. One runs in Nuki's cloud, and software calls it to control locks remotely, from anywhere. Another runs in the small box called a , which links the lock to the home's Wi-Fi, and it only answers calls from the same local network.
The document that describes the local API of Nuki's bridge carries a history of fourteen versions, from 1.6 in June 2017 to 1.13.3 in October 2024 (Nuki, Bridge API 1.13.3, PDF).
A new lock model usually changes nothing in it: a lock that behaves like the previous one talks to the same API, byte for byte, as the Smart Lock 2.0 did after the 1.0. What forces a change is a device that does something the API had no way to describe yet. Five of the fourteen versions are of that kind:
- In May 2019, version 1.9 introduced "Device Types," because the Opener, an
intercom module, is not a lock. The calls that address a device gained a
new
deviceTypeparameter. - In July 2020, version 1.11 added door sensor states.
- In September 2020, version 1.12 added the keypad's battery state.
- In November 2021, version 1.13.0 added the Smart Door to the list of types. The Smart Lock 3.0, released at the same time, only got one more value in that list.
- In December 2021, version 1.13.1 added the states of an external door sensor.
Two more versions strengthen security. The remaining seven only touch the documentation, fixes, or conveniences in how calls are made.
Even a convenience can depend on the hardware. In January 2020, version 1.10
added "simple lock actions," a /lock call and an /unlock call, which
only work if the bridge and the lock each run recent enough firmware. The
API reports both versions, but the bridge reads the lock's only once a day
(Nuki, developer
forum),
so the software calling it has two versions to check, one of them possibly
out of date, before it knows whether the call will work.
Wherever it can, the maker tries to make sure none of these additions breaks
existing software, because nothing can force the software already using the
API to update. The deviceType parameter introduced in 2019, for instance,
"defaults to 0," which stands for the only device type there was at first,
locks. That way Nuki makes sure a call written before 2019, which never sent
this parameter, keeps working. Applications from before 2019 can still lock
and unlock the locks that existed then without errors. They will not,
however, know the device types or sensor states added since, and they will
not know what to do with them when the bridges send them.
Nuki's cloud API, the one software calls remotely, changed the same way, by addition. It sends webhooks, messages that Nuki's cloud sends to the software when a lock changes state. Version 1.0 of these webhooks came out in December 2020, after several closed betas. The first beta, built on different call addresses, "will still be available for now," with a request to switch because it "most likely will be deprecated in the course of the year 2021" (Nuki, Web API webhooks). Two ways of receiving these messages were therefore in service at the same time, until every piece of software had moved over, and software connected to this API had to be able to read both.
Security gets tightened through new versions, without invalidating the old ones
Alongside its locks, Nuki sells a small box called a bridge, which plugs into
an outlet and links the lock to the home's Wi-Fi. The box answers calls
coming from the home's local network. Those calls make up Nuki's local API,
which Nuki describes in a public document, the Bridge API. To unlock the
door, software calls an address on the box, the way you would open a web
page:
http://192.168.1.50:8080/lockAction?nukiId=1&deviceType=0&action=1&token=123456.
The last part of the address, the token, is a password. The box only carries
out the order if the token is the one it knows.
Sending a password in an address, over plain HTTP, is a well-known problem. Any device able to capture traffic on that network can read the request, and anyone who has read it can send it again, unchanged, and open the door themselves. So Nuki changed the way software authenticates, in two steps.
The first step is the hashed token. Instead of the password, the software sends the time, a random number, and a hash, the result of a calculation made from those two values and the password, which cannot be run backward. The box does the same calculation on its side and compares. A captured request is no longer any use, because the box rejects a hash that is too old or that it has already received. The second step is the encrypted token, which leaves nothing of the token readable in the address and is only valid for sixty seconds.
The hashed token arrived in version 1.8 of the document, in March 2019, "as a more secure alternative to sending the plain token" (Nuki, Bridge API 1.13.3, PDF). The encrypted token arrived in version 1.13.2, in June 2022. In version 1.13.3, from October 2024, the hashed token is marked "deprecated." And the plain token, the password written into the address, is still accepted: the document reserves it "for testing and in private, secured WIFIs or VLANs," but it works.
In seven years, then, the maker added two ways to authenticate and removed none. Removing one would break, the same day, every third-party application still using it, and those applications are not the maker's. Software that integrates this kind of API therefore has to keep all three ways to authenticate in its code, and nothing says when it will be able to drop one.
The maker changes its rules and sets a date
New API versions usually add possibilities without invalidating the old ones, so that software written before they came out keeps working.
A maker can, however, decide to remove a feature, change the rules of a call, or put that call under a new condition. When that happens, software written before the change stops working. The trade calls this a breaking change, a change that breaks existing software, and the maker usually announces it with a date. Four public examples show four ways of doing it.
The first example comes from Salto, which designs locks for offices and apartment buildings and publishes a cloud API for its KS platform. In February 2019, Salto released version 1.1.10.6 of that platform, a simple maintenance release, and its release note said the update "introduces a breaking change for the GET entries and GET incidents endpoints." Those two calls returned a site's entry log and its list of incidents. The same note said Salto was "not supporting this for all deployed sites (yet)," and that for now data was only returned for test sites marked "early birds" (Salto, Connect API release v1.1.10.6). The same call therefore did not behave the same way on every site, and software reading that log across several sites had to cope with both behaviors. You can imagine the contortions this kind of maintenance demands when you integrate hundreds of different APIs.
The second example comes from Nuki's cloud API. Among other uses, that API serves short-term rental software, which creates and deletes access codes for guests. In June 2023, Nuki published version 1.5.0 of the API with a warning. Starting September 1, 2023, it said, the affected calls "will return an error message if the Smart Lock or Smart Door doesn't have an active Smart Hosting subscription," the subscription Nuki offers to hosts. Version 1.4.0 was deprecated on August 31, and the note added that "this may result in application breakage" (Nuki, Web API v1.5.0). The locks had not changed, and neither had the shape of the API calls. Only a subscription condition had been added, and software that worked one day was stuck the next, while the locks kept working.
The third example is a platform change. In 2023, outside the United States and Canada, Yale replaced its Yale Access app with a new one, Yale Home, and announced that "services from the Yale Access app will cease to operate from the 1st of July 2023" (Yale, Introducing the new Yale Home App). Links with other services, such as Airbnb, Google Home, or SmartThings, did not transfer over and had to be re-established on the new platform. A support page kept track of them, integration by integration and region by region, marked "Available" or "Coming Soon" (Yale, Yale Access to Yale Home integrations). Software connected to the old platform did not just have a new version to support. Each of its links with a Yale product had to be re-established, with a cutoff date.
The fourth example comes from a platform rather than a lock maker. SmartThings, Samsung's smart home platform, controls devices from many brands in one app. To talk to each of them, it uses a small program called a driver, which translates SmartThings' orders into the device's language. For years, those drivers were written in a programming language called Groovy.
In August 2022, SmartThings announced it was leaving Groovy behind. The old drivers would be replaced by drivers from a new system, called Edge, starting September 30, and certain functions of the tools used to write them would be removed on October 15. The same announcement warned that devices that "have not been supported for some time by their manufacturers on the legacy platform" "will not transition" (SmartThings, The End of Groovy Has Arrived).
Locks controlled through SmartThings therefore changed drivers without their makers doing anything. Locks whose makers no longer maintained them were not migrated at all. That is why software that goes through a platform has to keep up with that platform's versions, on top of each maker's.
Each event leaves a layer of logic in the integrator's code, and none removes one
Each of these events that brings a new API version requires the software integrating with these APIs to add another layer of logic to route between the possibilities.
Even when integrating a single maker's API, you may need a whole layer of conditional logic to handle new device types or states that did not exist at first, to carry different authentication methods and pick the right one for the bridge, to check that the bridge and the lock are each recent enough for the function being called, and so on. You may have to handle a subscription error that appeared on a given date while keeping the earlier behavior for locks it does not apply to, or even redo an integration entirely when one platform replaces another.
All these layers of logic add up, because each time, the service your software provides involves other parties, physical sites or applications that keep using the old versions.
Then you have to start over with the next brand, each with its own twists and often the same constraints (new devices, security, compliance, third-party dependencies, and so on).

| Who decides | What the integrator sees | What it has to keep | |
|---|---|---|---|
| The catalog grows | The maker, product by product | Device types and states its code does not know | Tolerance for values it does not know yet |
| Security gets tightened | The maker, without removing the old way to authenticate | Several ways to authenticate accepted for the same call | All of them, and choosing the right one for the bridge |
| The rules change | The maker, with a date | An announced breaking change, a new error, a migration | The old behavior until the date, the new one after |
The first two rows add capabilities, the third removes a feature on an announced date. None of them lets the software stop supporting the earlier versions.
What we have just described is the work Seam does on its customers' behalf. We track these versions maker by maker and support all of them behind a single API. Software that controls a lock through us has no need to know the versions of the bridge and the lock on the other end, or to keep three ways to authenticate. In another article, we explain what this layer adds on top of manufacturers' APIs.