Nuki Web API authorization update/synchronization inconsistency (production issue)

Discussion
1

Hello,

we are integrating the official Nuki Web API for production reservation/access management and we are observing reproducible inconsistencies between:

  • the Nuki Web API state,
  • Nuki Web cloud state,
  • and the actual physical Smart Lock / Keypad state.

Environment

  • Nuki Smart Lock Gen3 + Keypad
  • Nuki Web API (https://api.nuki.io )
  • direct REST calls via backend and Postman
  • no Bridge API involved

Smartlock example: Production Lock Go Gen 3

Main observed issues

1. Authorization create works relatively reliably

Creating keypad authorizations via API usually works correctly:

POST /smartlock/{smartlockId}/auth

The authorization appears in:

  • Nuki Web
  • API listing
  • and usually also propagates to keypad correctly.

2. Authorization update is inconsistent

Updating existing authorizations via:

POST /smartlock/{smartlockId}/auth/{id}

is inconsistent.

Observed behaviors:

  • sometimes works,
  • sometimes cloud state differs from actual keypad state.

3. Partial update can silently remove time restrictions

Example:

Sending only:

{
  "name": "TEST-0805",
  "code": 432426
}

successfully renames the authorization BUT silently removes:

  • allowedFromDate
  • allowedUntilDate
  • allowedWeekDays
  • allowedFromTime
  • allowedUntilTime

This effectively breaks the reservation time window.

To safely rename an auth we had to send the FULL original timing payload again:

{
  "name": "TEST-0805",
  "code": 432426,
  "allowedFromDate": "...",
  "allowedUntilDate": "...",
  "allowedWeekDays": 127,
  "allowedFromTime": 0,
  "allowedUntilTime": 0
}

4. SERIOUS ISSUE - Cloud/API state sometimes differs from physical keypad state

We repeatedly observed situations where:

  • authorization exists in API,
  • authorization exists in Nuki Web,
  • lock is online and responsive,
  • but keypad does not yet accept the PIN.

Sometimes:

  • sync helps,
  • sometimes updating/renaming existing auth helps force propagation,
  • sometimes nothing changes for a while.

Important note

This issue is reproducible directly via isolated Postman requests against the official Nuki Web API, outside of our reservation system.

So this does not appear to be related to application/business logic.

Current workaround

We implemented:

  • periodic authorization audit,
  • automatic repair/recreate,
  • delayed sync,
  • and “gentle rename refresh” to force keypad propagation.

However update/delete reliability still appears problematic as well as renaming as update is not propagated and last days 2026/May/24th and further fails also when it is done via Nuki Web interface and even synchronization is not leading to aligning authorizations between keypad in Nuki App and Nuki Web.

Questions

  1. Is this a known synchronization issue between cloud and keypad?
  2. Are authorization updates eventually consistent internally?
  3. Is there an officially recommended way to force keypad propagation?
  4. Is partial update behavior (removing timing restrictions) intended?

Any clarification from the API team would be greatly appreciated.

Thank you.

3

Hi Martin,

Thanks for your detailed post regarding the problems you’ve been facing.

Creating and updating authorisations is an asynchronous process where the server needs to connect to the smart lock and create/update the authorisation. This can sometimes fail if a connection cannot be established with the smart lock (e.g. internet outage). More about that can be read here: Asynchronous API. I can only guess that some of your API request operations are failing; as a mediation we recommend webhooks which give you a confirmation when your operations were successfully executed (and also explains any errors when they occur). They are also explained in more detail in the aforementioned link. Looking furhter into this topic will indirectly address questions 1-3.

The behaviour in how those 5 allowed fields function is currently by design. We recommend always sending those 5 fields in your payload as a mitigation. This is a known topic we will look into with a future version of our API.

Hope that helps. Let me know if I can help any more.

4

Hi Andrew,

thank you for the clarification. This is helpful.

I understand that authorization create/update operations are asynchronous and that webhooks are the recommended way to receive confirmation whether an operation was successfully executed.

However, I would like to clarify the recommended recovery strategy.

A webhook can tell us whether the operation succeeded or failed, but it does not by itself solve what the integration should do when the operation fails.

For example:

  • if creating an authorization fails, should the integration retry the same create request?
  • if updating an authorization fails, should the integration retry the update, recreate the authorization, or leave the old one unchanged?
  • is there any recommended retry interval / backoff strategy?
  • should /smartlock/{smartlockId}/sync be used after failed or delayed authorization operations, or only in exceptional cases?
  • are duplicate keypad codes for the same time window handled safely, or should the integration avoid re-creating until it is sure the previous request failed?

In our case, creating authorizations is generally reliable, but update/delete operations and cloud-to-keypad propagation can be inconsistent. We want to implement the webhook-based flow correctly, but we also need a safe and recommended recovery path when a webhook reports failure or when no confirmation is received within a reasonable timeout.

Could you please clarify the recommended approach for error recovery and retries in production access-management scenarios?

Thank you.