TTLock API Integration Guide for Developers
Building against TTLock-compatible hardware means working with two different layers: a cloud API for account, lock and credential management, and a BLE SDK for talking to a lock directly over Bluetooth. This guide explains how the pieces fit together conceptually so you know what to ask for in the official developer documentation, without guessing at exact endpoints or parameters here.
Two layers: cloud API and BLE SDK
Smart Lukko is an independent third-party app for TTLock-compatible smart locks and is not affiliated with TTLock or Sciener; developers evaluating an integration should treat this article as a map of the territory, not a substitute for the vendor's own developer documentation.
- Cloud API. A hosted service that manages accounts, locks, gateways, passcodes, eKeys and unlock records as cloud resources. Operations that must reach a lock while you're not physically near it — issuing a remote passcode, triggering a remote unlock, pulling history — go through this layer and require a gateway bound to the lock.
- BLE SDK. A mobile/embedded library for talking to a lock directly over Bluetooth when the phone or device is in range. Pairing, writing offline passcodes, and reading the lock's local state typically happen this way, independent of whether a gateway exists.
Most production integrations use both: the BLE SDK for the in-person parts of the experience, and the cloud API for anything that needs to happen when nobody is standing next to the door.
Getting developer access
Access to the official cloud API and SDKs is granted through a developer account with the platform vendor, typically involving an application/registration step, issued credentials used to authenticate API calls, and a distinct set of keys per app or integration. Exact registration steps, credential formats and authentication flow are defined by the vendor and can change, so treat any third-party description — including this one — as directional rather than a spec.
- Register as a developer. Expect an application or account-creation step before you receive any credentials.
- Keep credentials per-application. Treat issued keys the same as any other API secret: unique per integration, rotated if leaked, never embedded in a client-side app that ships to end users.
- Read the current official docs before writing code. Endpoint paths, required parameters and response shapes are defined there and are the only source you should implement against.
Resources you will typically work with
| Resource | What it represents | Typical dependency |
|---|---|---|
| Lock | A registered physical lock bound to an account | None for read; gateway for remote commands |
| Gateway | The bridge that puts a lock's Bluetooth radio on the internet | Network connectivity, binding to specific locks |
| Passcode | A keypad code with its own validity rules | BLE to write offline; gateway to deliver/revoke remotely |
| eKey | Access delegated to another user's app account | Cloud account system; BLE or gateway to actually unlock |
| Unlock record | A log entry of an open/close/attempt event | Synced from the lock via BLE or gateway |
Rate limits, permissions and gateway dependency
Cloud APIs in this space commonly apply request-rate limits and scope credentials to what an app or integration is allowed to see and do — for example, restricting an integration to locks explicitly shared with it rather than every lock on the platform. Exact limits and permission models are set and documented by the vendor and can differ between account tiers, so budget for polling/backoff logic and don't assume unlimited throughput.
Remember that any "remote" capability in the API — unlocking, pushing a new passcode, pulling fresh records on demand — is gateway-dependent in practice. An integration that only calls the cloud API without confirming a gateway is online and bound will see failed or stale results for those operations even though the API call itself succeeds.
Where to get exact specs
Endpoint paths, required and optional parameters, authentication headers, response schemas, and current rate limits are defined by the official TTLock/Sciener developer documentation and change over time. Always implement against the current version of that documentation rather than any third-party summary, including this article, and reach out to the vendor's developer support for anything the docs leave ambiguous.
Frequently asked questions
Do I need the cloud API, the BLE SDK, or both?
It depends on your use case. If your integration only needs to act when a phone or device is physically near the lock, the BLE SDK alone may suffice. Anything remote — unlocking or issuing codes from afar — needs the cloud API plus a gateway.
Can I unlock a lock through the API without a gateway?
No. Remote operations depend on a gateway bound to the lock and online. Without one, the cloud API has no path to reach the lock, regardless of what the API call itself returns.
Where do I find the exact API endpoints and parameters?
In the official TTLock/Sciener developer documentation, which is the authoritative and only reliable source. Endpoint paths and parameter names aren't reproduced here because they change and vary by API version.
Are there rate limits on the cloud API?
Platforms in this space typically apply request-rate limits and permission scoping per developer account, but exact numbers are set by the vendor and can vary by tier. Build in backoff and retry logic rather than assuming unlimited calls.
Is Smart Lukko built on this same API?
Smart Lukko is an independent third-party app for TTLock-compatible smart locks and is not affiliated with TTLock or Sciener. This guide describes the general shape of the platform for developers, not Smart Lukko's own internals.