Managing Access Codes
Access codes are codes for keypad devices. These are used when you want to provide access to a lock using a PIN code.
What Is an Access Code?
An access code is a code used for a keypad or pinpad device. Unlike physical keys, which can easily be lost or duplicated, PIN codes can be customized, tracked, and altered on the fly. Using the Seam Access Code API, you can easily generate access codes on the hundreds of door lock models with which we integrate.
Seam supports programming two types of access codes: ongoing and time-bound. To differentiate between the two, refer to the type property of the access code. Ongoing codes display as ongoing, whereas time-bound codes are labeled time_bound.
In addition, for certain devices, Seam also supports offline access codes.
Ongoing Access Codes
Ongoing access code are ideal for residents or long-term users. Ongoing codes remain active on a device until they are removed. They can start right away or at a later date if you provide a starts_at timestamp.
Time-Bound Access Codes
Time-bound access codes are suitable for temporary access, like guest visits or service appointments. These codes operate between designated starts_at and ends_at timestamps, granting access only during this period.
Offline Access Codes
Offline access (PIN) codes are designed for door locks that might not always maintain an internet connection. Currently, Seam supports offline access codes for igloohome locks, dormakaba Oracode locks, and Lockly locks. For this type of access code, the device manufacturer uses encryption keys (tokens) to create server-based registries of algorithmically-generated offline PIN codes. Because the tokens remain synchronized with the managed devices, the locks do not require an active internet connection—and you do not need to be near the locks—to create an offline access code. Then, owners or managers can share these offline codes with users through a variety of mechanisms, such as messaging applications. That is, lock users do not need to install a smartphone application to receive an offline access code.
You cannot modify a created offline access code. In addition, you cannot revoke a created offline access code before the configured expiration date for the code. To invalidate an offline access code before the expiration date, you must either perform a factory reset on the device or re-pair your smartphone with the device.
Seam supports two types of offline access codes: time-bound and one-time-use. Note that this support varies based on the device manufacturer. Before creating an offline access code, it is imperative to understand any manufacturer- or device-specific constraints, such as the maximum number of access codes, any time slot or activation requirements, and so on. For details, see the corresponding device guide.
Time-Bound Offline Access Codes
For igloohome locks and dormakaba Oracode locks, you can create time-bound offline access codes with validity durations at either the hour level or the day level. For Lockly locks, you can create generic time-bound offline access codes that do not differentiate between hourly-bound and daily-bound codes.
Hourly-bound offline access codes are intended for shorter durations, while daily-bound offline codes are intended for longer durations. Device manufacturers set the bounds for these short- and long-term access codes, and some device manufacturers enforce a maximum duration for hourly-bound offline access codes. See the corresponding device guide for more information.
To create an hourly-bound or generic time-bound offline access code, specify the desired starts_at and ends_at date and time. To create a daily-bound offline access code, you must specify the same time in the starts_at and ends_at properties.
One-Time-Use Offline Access Codes
For igloohome locks and Lockly locks, you can create one-time-use offline access codes. igloohome one-time-use offline access codes are valid for 24 hours from the starts_at timestamp that you configure. Lockly offline access codes are valid for the time period that you specify using the starts_at and ends_at timestamps. These codes expire after a single use.
How Seam Programs Codes onto the Lock
Seam ensures access reliability by initiating the programming of access codes onto the lock ahead of its starts_at time. This approach minimizes the risks of delays or disruptions during the programming process.
Native Scheduling
For locks that support setting codes with a schedule, Seam will preload access codes onto the device a full 72 hours before the starts_at timestamp of a time-bound code. When the starts_at time arrives, the code automatically activates and will remain active until its ends_at time. We enable this "native scheduling" functionality by default for all providers that support it. See Native Scheduling—Supported Providers for a list of supported providers. You can choose to override this default behavior and have Seam perform "just-in-time scheduling" by setting prefer_native_scheduling to false when creating a code.
Native Scheduling—Supported Providers
| ✅ Supported | ✖️ Not Supported |
|---|---|
2N | Dormakaba Oracode |
August | Lockly |
Igloohome | SmartThings |
Kwikset | |
Nuki | |
Salto | |
Schlage | |
Tedee | |
TTLock | |
Yale | |
Wyze |
Just-in-time Scheduling
For those locks that lack native scheduling functionality, Seam will use its own scheduling infrastructure to program the code 30 minutes before the starts_at time, and remove it at the ends_at time.
Linking Unlock Events and Access Codes
When a user unlocks a door using an access code, Seam issues a lock.unlocked event. Some device manufacturers include the ID of the access code in lock-related events. This information is useful for troubleshooting and logging. Further, if you name access codes in a way that identifies the associated users, you can use these lock.unlocked events to identify the users who unlocked the doors.
Currently, the following device manufacturers send the access_code_id in the lock.unlocked event:
August
Salto KS
Schlage
Tedee
TTLock
Yale
Advanced Feature: Backup Access Codes
Occasionally, Seam may encounter issues when programming codes onto locks. Such hiccups can arise from device connectivity issues, manual interventions from the lock or its accompanying app, or service disruptions from the lock providers. Given these issues, we strongly advise preprogramming a set of backup codes onto the door lock. Should you detect a failure in access code programming, these backup codes can be promptly shared.
Seam offers a Backup Access Code service. When activated, this service automatically maintain a pool of pre-programmed access codes on a device. These codes are programmed in addition to the regular access codes on Seam, acting as a safety net in case of any issues with the primary codes. Please read about how to enable and request a back up code here.
Last updated
