From your request to the lock

1. You make a change. For example, you give someone a PIN or send an unlock command. The API saves the change and queues it for the lock.

2. The lock connects. Locks connect to the cloud, not the other way round. A lock checks in on its heartbeat, and when someone uses it if its wake_wifi setting allows. An always-on lock gets a notice as soon as a change is waiting, and connects to download it.

3. The lock applies the change and confirms it. Only then does the change show as done. For example, a grant's sync_status changes from pending to synced.

4. Unconfirmed changes are retried automatically. If the lock doesn't confirm a change, the cloud sends it again at a later check-in. If the lock can't apply it, it's marked failed.

​

How locks connect

• Wi-Fi. To save battery, a lock's Wi-Fi sleeps between check-ins. The lock starts each check-in over a secure HTTPS connection. In one check-in it uploads its events and status, and downloads any waiting changes.

• Always-on. Some models can stay connected all the time. When a change is waiting, the cloud notifies the lock straight away, and the lock connects to download it.

• Bluetooth. The KoreLock Admin app can pass a lock's check-in to the cloud over Bluetooth, so a lock can sync even without Wi-Fi.

• Retries. If a check-in fails, the lock tries again automatically.

​

Mobile apps

• KoreLock Admin app: registers locks, connects them to Wi-Fi, and installs firmware updates, all over Bluetooth.

• Entry app: lets a credential holder unlock with their phone over Bluetooth. The app downloads a signed credential from the cloud, and the lock checks it itself, so it works even when the lock is offline.

​

What works offline

A lock doesn't need a connection to let people in. These work offline:

• PINs and cards that have already synced to the lock.

• SmartPINs, which the lock checks itself, so they work as soon as you create them.

• Entry app credentials.

While offline, the lock keeps its events and uploads them, oldest first, at its next check-in.

​

Getting events

Use webhooks to get events. When something happens on a lock, KoreLock sends the event to your server as soon as the lock uploads it.

• Don't poll for events. A lock uploads its events only when it checks in, so asking again and again doesn't get them sooner. It only uses up your rate limit.

• What webhooks send: access events (locks, unlocks, and denied attempts) and credential_holder_grant_sync events (grants added to or removed from a lock). To know when a grant reaches a lock, listen for credential_holder_grant_sync instead of reading the grant again.

• Other events: events such as battery and door_state aren't sent by webhook. List events when you need them, not on a timer.

• Reply quickly: answer each delivery with a 2xx status within 3 seconds. Failed deliveries are retried automatically, so an event can arrive late, more than once, or out of order. Use the event's id to skip duplicates.

• Check the signature: set a secret on the webhook, and KoreLock signs each delivery so you can check it came from KoreLock.

​

Staying within rate limits

Each limit resets every minute. Limits are counted per user for authorization code tokens, and per account for client credentials tokens.

• All writes (POST, PUT, and DELETE combined): 60 per minute

• Lock events: 30 per minute

• All other reads: 120 per minute

Over a limit, the API returns 429 Too Many Requests with a Retry-After header. Wait that many seconds, then try again. See rate limits for details.

​

Best practices

• Get events from webhooks, not by polling.

• Treat a change as done only when the lock confirms it, for example when sync_status is synced.

• Make fewer requests: ask for bigger pages (per_page up to 250), and don't re-read data that hasn't changed.