# KoreLock API

> Manage smart locks, credentials and access for KoreLock-powered devices.

The KoreLock API is a REST API for managing locks, locations and the people who can open them. Authenticate with an OAuth 2.0 bearer token. Changes are queued and reach a lock when it next syncs. The full OpenAPI 3.1 spec is linked below and is the source of truth.

- [OpenAPI spec (YAML)](https://app.korelock.com/api/docs/openapi.yaml)
- [OpenAPI spec (JSON)](https://app.korelock.com/api/docs/openapi.json)
- [API reference](https://app.korelock.com/api/docs/)
- [Release notes](https://app.korelock.com/api/docs/release-notes/): what changed in the API each month
- [Lock specification guide](https://app.korelock.com/api/docs/lock-specs/): setting ranges and defaults, limits, and the capabilities of every lock model

## Guides

- [Quick start](https://app.korelock.com/api/docs/#description/quick-start)
- [1. Get an access token](https://app.korelock.com/api/docs/#description/1-get-an-access-token)
- [2. Register a lock](https://app.korelock.com/api/docs/#description/2-register-a-lock)
- [3. Lock and unlock over Wi-Fi](https://app.korelock.com/api/docs/#description/3-lock-and-unlock-over-wi-fi)
- [4. Give someone a PIN](https://app.korelock.com/api/docs/#description/4-give-someone-a-pin)
- [5. Read lock events](https://app.korelock.com/api/docs/#description/5-read-lock-events)
- [Use with AI assistants](https://app.korelock.com/api/docs/#description/use-with-ai-assistants)
- [What the assistant can do](https://app.korelock.com/api/docs/#description/what-the-assistant-can-do)
- [Claude](https://app.korelock.com/api/docs/#description/claude)
- [Claude Desktop](https://app.korelock.com/api/docs/#description/claude-desktop)
- [ChatGPT](https://app.korelock.com/api/docs/#description/chatgpt)
- [Claude Code](https://app.korelock.com/api/docs/#description/claude-code)
- [Codex](https://app.korelock.com/api/docs/#description/codex)
- [API conventions](https://app.korelock.com/api/docs/#description/api-conventions)
- [Identifiers](https://app.korelock.com/api/docs/#description/identifiers)
- [Pagination](https://app.korelock.com/api/docs/#description/pagination)
- [Errors](https://app.korelock.com/api/docs/#description/errors)
- [How changes reach a lock](https://app.korelock.com/api/docs/#description/how-changes-reach-a-lock)
- [Rate limits](https://app.korelock.com/api/docs/#description/rate-limits)

## Getting started

### [Authentication](https://app.korelock.com/api/docs/#tag/authentication)

KoreLock uses OAuth 2.0.

- [Get an access token](https://app.korelock.com/api/docs/#tag/authentication/POST/oauth/token): `POST /oauth/token`. Exchanges client credentials, an authorization code or a refresh token for an access token.
- [Revoke a token](https://app.korelock.com/api/docs/#tag/authentication/POST/oauth/revoke): `POST /oauth/revoke`. Revokes an access token or refresh token.

## Resources

### [Locations](https://app.korelock.com/api/docs/#tag/locations)

Locations group locks by physical place.

- [List locations](https://app.korelock.com/api/docs/#tag/locations/GET/v1/locations): `GET /v1/locations`
- [Create a location](https://app.korelock.com/api/docs/#tag/locations/POST/v1/locations): `POST /v1/locations`
- [Get a location](https://app.korelock.com/api/docs/#tag/locations/GET/v1/locations/{location_id}): `GET /v1/locations/{location_id}`
- [Update a location](https://app.korelock.com/api/docs/#tag/locations/PUT/v1/locations/{location_id}): `PUT /v1/locations/{location_id}`. Changes the location's details.
- [Delete a location](https://app.korelock.com/api/docs/#tag/locations/DELETE/v1/locations/{location_id}): `DELETE /v1/locations/{location_id}`. Deletes the location.

### [Models & capabilities](https://app.korelock.com/api/docs/#tag/lock-models)

KoreLock powers locks from several product lines, from keypad locks to card-only locks.

- [List models and capabilities](https://app.korelock.com/api/docs/#tag/lock-models/GET/v1/locks/models): `GET /v1/locks/models`. Lists every lock model and its capabilities.

### [Locks](https://app.korelock.com/api/docs/#tag/locks)

A lock has main attributes you can set, like its name and location, and state attributes it reports on each sync, like battery level and whether it's locked.

- [List locks](https://app.korelock.com/api/docs/#tag/locks/GET/v1/locks): `GET /v1/locks`. Lists every lock registered to the account.
- [Register a lock](https://app.korelock.com/api/docs/#tag/locks/POST/v1/locks): `POST /v1/locks`. Most locks are registered in the KoreLock white-label app, which also connects them to Wi-Fi.
- [Get a lock](https://app.korelock.com/api/docs/#tag/locks/GET/v1/locks/{lock_id}): `GET /v1/locks/{lock_id}`. Returns the lock's main and state attributes.
- [Update a lock](https://app.korelock.com/api/docs/#tag/locks/PUT/v1/locks/{lock_id}): `PUT /v1/locks/{lock_id}`. Only `name` and `location_id` can be changed.
- [Deregister a lock](https://app.korelock.com/api/docs/#tag/locks/DELETE/v1/locks/{lock_id}): `DELETE /v1/locks/{lock_id}`. Removes the lock from your account.
- [Lock](https://app.korelock.com/api/docs/#tag/locks/PUT/v1/locks/{lock_id}/lock): `PUT /v1/locks/{lock_id}/lock`. Queues a lock command.
- [Unlock](https://app.korelock.com/api/docs/#tag/locks/PUT/v1/locks/{lock_id}/unlock): `PUT /v1/locks/{lock_id}/unlock`. Queues an unlock command.
- [Cancel a pending command](https://app.korelock.com/api/docs/#tag/locks/PUT/v1/locks/{lock_id}/cancel_pending_action): `PUT /v1/locks/{lock_id}/cancel_pending_action`. Cancels a queued lock or unlock command and clears `pending_state`, as long as the lock hasn't fetched the command yet.

### [Settings](https://app.korelock.com/api/docs/#tag/settings)

Settings control how a lock behaves: auto-lock, sound, keypad lockout, card readers, Wi-Fi and more.

- [Get settings](https://app.korelock.com/api/docs/#tag/settings/GET/v1/locks/{lock_id}/settings): `GET /v1/locks/{lock_id}/settings`. Returns the lock's current settings.
- [Update settings](https://app.korelock.com/api/docs/#tag/settings/PUT/v1/locks/{lock_id}/settings): `PUT /v1/locks/{lock_id}/settings`. Changes the lock's settings.

## Access & credentials

### [Credential holders](https://app.korelock.com/api/docs/#tag/credential-holders)

A credential holder is a person, or a shared role such as "Cleaning crew", who has one or more credentials: a PIN, a card, an Entry app credential or a UniKey mobile credential.

- [List credential holders](https://app.korelock.com/api/docs/#tag/credential-holders/GET/v1/credential_holders): `GET /v1/credential_holders`. Lists the account's credential holders, sorted by name.
- [Create a credential holder](https://app.korelock.com/api/docs/#tag/credential-holders/POST/v1/credential_holders): `POST /v1/credential_holders`. Creates a credential holder.
- [Get a credential holder](https://app.korelock.com/api/docs/#tag/credential-holders/GET/v1/credential_holders/{credential_holder_id}): `GET /v1/credential_holders/{credential_holder_id}`. Returns a credential holder.
- [Update a credential holder](https://app.korelock.com/api/docs/#tag/credential-holders/PUT/v1/credential_holders/{credential_holder_id}): `PUT /v1/credential_holders/{credential_holder_id}`. Changes a credential holder's details and credentials.
- [Remove a credential holder](https://app.korelock.com/api/docs/#tag/credential-holders/DELETE/v1/credential_holders/{credential_holder_id}): `DELETE /v1/credential_holders/{credential_holder_id}`. Removes the credential holder and revokes all of their grants.

### [Grants](https://app.korelock.com/api/docs/#tag/grants)

A grant gives one credential holder access to one lock.

- [List grants for a credential holder](https://app.korelock.com/api/docs/#tag/grants/GET/v1/credential_holders/{credential_holder_id}/grants): `GET /v1/credential_holders/{credential_holder_id}/grants`. Lists the credential holder's grants.
- [Create a grant](https://app.korelock.com/api/docs/#tag/grants/POST/v1/credential_holders/{credential_holder_id}/grants): `POST /v1/credential_holders/{credential_holder_id}/grants`. Gives the credential holder access to a lock.
- [Get a grant](https://app.korelock.com/api/docs/#tag/grants/GET/v1/credential_holders/{credential_holder_id}/grants/{grant_id}): `GET /v1/credential_holders/{credential_holder_id}/grants/{grant_id}`. Returns the grant, including its `lock`.
- [Update a grant](https://app.korelock.com/api/docs/#tag/grants/PUT/v1/credential_holders/{credential_holder_id}/grants/{grant_id}): `PUT /v1/credential_holders/{credential_holder_id}/grants/{grant_id}`. Changes the grant's access times or schedules.
- [Revoke a grant](https://app.korelock.com/api/docs/#tag/grants/DELETE/v1/credential_holders/{credential_holder_id}/grants/{grant_id}): `DELETE /v1/credential_holders/{credential_holder_id}/grants/{grant_id}`. Removes the credential holder's access to the lock.
- [List grants for a lock](https://app.korelock.com/api/docs/#tag/grants/GET/v1/locks/{lock_id}/grants): `GET /v1/locks/{lock_id}/grants`. Lists every grant on the lock, current and expired.
- [List current grants for a lock](https://app.korelock.com/api/docs/#tag/grants/GET/v1/locks/{lock_id}/grants/current): `GET /v1/locks/{lock_id}/grants/current`. Lists the lock's grants that haven't expired (`expired: false`), including ones that haven't started yet.
- [List expired grants for a lock](https://app.korelock.com/api/docs/#tag/grants/GET/v1/locks/{lock_id}/grants/expired): `GET /v1/locks/{lock_id}/grants/expired`. Lists the lock's expired grants (`expired: true`), worked out in the lock's local time.

### [SmartPINs](https://app.korelock.com/api/docs/#tag/smartpins)

A SmartPIN is a time-limited PIN for guests that works without a network connection.

- [List SmartPINs](https://app.korelock.com/api/docs/#tag/smartpins/GET/v1/locks/{lock_id}/smart_pins): `GET /v1/locks/{lock_id}/smart_pins`. Lists every SmartPIN on the lock, current and expired.
- [Create a SmartPIN](https://app.korelock.com/api/docs/#tag/smartpins/POST/v1/locks/{lock_id}/smart_pins): `POST /v1/locks/{lock_id}/smart_pins`. Generates a 10-digit SmartPIN for the lock.
- [List current SmartPINs](https://app.korelock.com/api/docs/#tag/smartpins/GET/v1/locks/{lock_id}/smart_pins/current): `GET /v1/locks/{lock_id}/smart_pins/current`. Lists the lock's SmartPINs that haven't expired (`expired: false`).
- [List expired SmartPINs](https://app.korelock.com/api/docs/#tag/smartpins/GET/v1/locks/{lock_id}/smart_pins/expired): `GET /v1/locks/{lock_id}/smart_pins/expired`. Lists the lock's expired SmartPINs (`expired: true`), worked out in the lock's local time.
- [Get a SmartPIN](https://app.korelock.com/api/docs/#tag/smartpins/GET/v1/locks/{lock_id}/smart_pins/{smart_pin_id}): `GET /v1/locks/{lock_id}/smart_pins/{smart_pin_id}`. Returns a SmartPIN, including its `pin`.
- [Update a SmartPIN](https://app.korelock.com/api/docs/#tag/smartpins/PUT/v1/locks/{lock_id}/smart_pins/{smart_pin_id}): `PUT /v1/locks/{lock_id}/smart_pins/{smart_pin_id}`. Changes a SmartPIN's `name` or `email`.

## Schedules

### [Action schedules](https://app.korelock.com/api/docs/#tag/action-schedules)

Action schedules lock and unlock a lock automatically at set times each week.

- [List action schedules](https://app.korelock.com/api/docs/#tag/action-schedules/GET/v1/action_schedules): `GET /v1/action_schedules`. Sorted by name.
- [Create an action schedule](https://app.korelock.com/api/docs/#tag/action-schedules/POST/v1/action_schedules): `POST /v1/action_schedules`
- [Get an action schedule](https://app.korelock.com/api/docs/#tag/action-schedules/GET/v1/action_schedules/{action_schedule_id}): `GET /v1/action_schedules/{action_schedule_id}`
- [Update an action schedule](https://app.korelock.com/api/docs/#tag/action-schedules/PUT/v1/action_schedules/{action_schedule_id}): `PUT /v1/action_schedules/{action_schedule_id}`. Changes the schedule's name or times.
- [Remove an action schedule](https://app.korelock.com/api/docs/#tag/action-schedules/DELETE/v1/action_schedules/{action_schedule_id}): `DELETE /v1/action_schedules/{action_schedule_id}`. Removes the schedule.

### [Auto-lock schedules](https://app.korelock.com/api/docs/#tag/auto-lock-schedules)

Auto-lock schedules turn a lock's auto-lock on and off at set times each week.

- [List auto-lock schedules](https://app.korelock.com/api/docs/#tag/auto-lock-schedules/GET/v1/auto_lock_schedules): `GET /v1/auto_lock_schedules`. Sorted by name.
- [Create an auto-lock schedule](https://app.korelock.com/api/docs/#tag/auto-lock-schedules/POST/v1/auto_lock_schedules): `POST /v1/auto_lock_schedules`
- [Get an auto-lock schedule](https://app.korelock.com/api/docs/#tag/auto-lock-schedules/GET/v1/auto_lock_schedules/{auto_lock_schedule_id}): `GET /v1/auto_lock_schedules/{auto_lock_schedule_id}`
- [Update an auto-lock schedule](https://app.korelock.com/api/docs/#tag/auto-lock-schedules/PUT/v1/auto_lock_schedules/{auto_lock_schedule_id}): `PUT /v1/auto_lock_schedules/{auto_lock_schedule_id}`. Changes the schedule's name or times.
- [Remove an auto-lock schedule](https://app.korelock.com/api/docs/#tag/auto-lock-schedules/DELETE/v1/auto_lock_schedules/{auto_lock_schedule_id}): `DELETE /v1/auto_lock_schedules/{auto_lock_schedule_id}`. Removes the schedule.

### [Week schedules](https://app.korelock.com/api/docs/#tag/week-schedules)

Week schedules limit when a credential works.

- [List week schedules](https://app.korelock.com/api/docs/#tag/week-schedules/GET/v1/week_schedules): `GET /v1/week_schedules`. Sorted by name.
- [Create a week schedule](https://app.korelock.com/api/docs/#tag/week-schedules/POST/v1/week_schedules): `POST /v1/week_schedules`
- [Get a week schedule](https://app.korelock.com/api/docs/#tag/week-schedules/GET/v1/week_schedules/{week_schedule_id}): `GET /v1/week_schedules/{week_schedule_id}`
- [Update a week schedule](https://app.korelock.com/api/docs/#tag/week-schedules/PUT/v1/week_schedules/{week_schedule_id}): `PUT /v1/week_schedules/{week_schedule_id}`. Changes the schedule's name or times.
- [Remove a week schedule](https://app.korelock.com/api/docs/#tag/week-schedules/DELETE/v1/week_schedules/{week_schedule_id}): `DELETE /v1/week_schedules/{week_schedule_id}`. Removes the schedule.

### [Holiday schedules](https://app.korelock.com/api/docs/#tag/holiday-schedules)

Holiday schedules block credentials on certain dates.

- [List holiday schedules](https://app.korelock.com/api/docs/#tag/holiday-schedules/GET/v1/holiday_schedules): `GET /v1/holiday_schedules`. Sorted by name.
- [Create a holiday schedule](https://app.korelock.com/api/docs/#tag/holiday-schedules/POST/v1/holiday_schedules): `POST /v1/holiday_schedules`
- [Get a holiday schedule](https://app.korelock.com/api/docs/#tag/holiday-schedules/GET/v1/holiday_schedules/{holiday_schedule_id}): `GET /v1/holiday_schedules/{holiday_schedule_id}`
- [Update a holiday schedule](https://app.korelock.com/api/docs/#tag/holiday-schedules/PUT/v1/holiday_schedules/{holiday_schedule_id}): `PUT /v1/holiday_schedules/{holiday_schedule_id}`. Changes the schedule's name or times.
- [Remove a holiday schedule](https://app.korelock.com/api/docs/#tag/holiday-schedules/DELETE/v1/holiday_schedules/{holiday_schedule_id}): `DELETE /v1/holiday_schedules/{holiday_schedule_id}`. Removes the schedule.

## Events & webhooks

### [Events](https://app.korelock.com/api/docs/#tag/events)

The lock creates an event every time something happens: an unlock, a denied PIN, a battery warning, a sync.

- [List events](https://app.korelock.com/api/docs/#tag/events/GET/v1/locks/{lock_id}/events): `GET /v1/locks/{lock_id}/events`. Lists the lock's events, newest recorded first.
- [Get an event](https://app.korelock.com/api/docs/#tag/events/GET/v1/locks/{lock_id}/events/{event_id}): `GET /v1/locks/{lock_id}/events/{event_id}`

### [Webhooks](https://app.korelock.com/api/docs/#tag/webhooks)

A webhook tells KoreLock to send events to your server as they happen, so you don't have to poll.

- [List webhooks](https://app.korelock.com/api/docs/#tag/webhooks/GET/v1/webhooks): `GET /v1/webhooks`
- [Create a webhook](https://app.korelock.com/api/docs/#tag/webhooks/POST/v1/webhooks): `POST /v1/webhooks`. Starts sending the subscribed event types to `url`.
- [Get a webhook](https://app.korelock.com/api/docs/#tag/webhooks/GET/v1/webhooks/{webhook_id}): `GET /v1/webhooks/{webhook_id}`
- [Update a webhook](https://app.korelock.com/api/docs/#tag/webhooks/PUT/v1/webhooks/{webhook_id}): `PUT /v1/webhooks/{webhook_id}`. Changes the webhook's URL, secret or subscribed events, or turns it on or off with `enabled`.
- [Delete a webhook](https://app.korelock.com/api/docs/#tag/webhooks/DELETE/v1/webhooks/{webhook_id}): `DELETE /v1/webhooks/{webhook_id}`. Removes the webhook and stops new deliveries to it.
- [access event](https://app.korelock.com/api/docs/#tag/webhooks/webhook/POST/access): `POST to your webhook URL`. An access event: a lock, unlock or denied attempt.
- [credential_holder_grant_sync event](https://app.korelock.com/api/docs/#tag/webhooks/webhook/POST/credential-holder-grant-sync): `POST to your webhook URL`. A grant was added to or removed from a lock.