Managing Offline Access Codes

Learn how to create offline access codes for applicable smart locks with keypads.

Overview

This guide explains how to create offline access (PIN) codes for smart locks that support these types of codes. Use the Access Codes API to generate a time-bound or one-time-use offline access code. Note that Seam support for offline access code functions varies depending on the device manufacturer. For details, see the corresponding device guide.

For information about online access codes, see Managing Access Codes.


Before You Begin: Confirm Capabilities

Before you attempt to create an offline access code, be sure to confirm that your device has the capability to perform this operation. You can check the following capability flag for the device:

  • can_program_offline_access_codes

Use Get Device (or Get Lock) for a specific device to return this capability flag. Then, use an if statement or similar check to confirm that this flag is both present and true before attempting to create an offline access code.

Further, 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 and any manufacturer-specific properties within the retrieved lock.

Request:

seam.locks.get(device="11111111-1111-1111-1111-444444444444")

Response:

Device(
  device_id='11111111-1111-1111-1111-444444444444',
  can_program_offline_access_codes=True, // You can create offline access codes for this device.
  ...
)

Creating 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.

Some device manufacturers enforce a maximum duration for hourly-bound offline access codes. For example, igloohome and dormakaba Oracode enforce the following duration rules for hourly- and daily-bound offline access codes:

ManufacturerCode TypeDuration Rule

igloohome

Hourly-bound codes

1 to 672 hours (28 days)

igloohome

Daily-bound codes

29 to 367 days

dormakaba Oracode

Hourly- or daily-bound codes

1 to 31 days

dormakaba Oracode locks also use specific access code time slots (called "user levels" or "user prefixes"). You must adhere to these time slots when you create offline access codes. For more information, see User Levels.

To create an hourly-bound offline access code, set is_offline_access_code to true, and specify the desired starts_at and ends_at date and time.

To create a daily-bound offline access code, set is_offline_access_code to true, and specify the same time (but not the same date) in the starts_at and ends_at properties. Because daily-bound offline access codes must be valid for a number of days, that is, day-level granularity, you can set max_time_rounding to 1day (or 1d), instead of the default 1hour (or 1h). In this case, Seam rounds the time period that you specify to the nearest day.

Program an Hourly-Bound Offline Access Code

To create an hourly-bound offline access code, first issue a creation request. Then, poll or use a webhook to confirm the successful code registration in the offline access code server that the device manufacturer maintains.

1. Create an Hourly-Bound Offline Access Code

To create an hourly-bound offline access code, provide the device_id of the lock for which you want to create the code and set is_offline_access_code to true. Specify the starts_at and ends_at ISO 8601 timestamps to define the active time window for the offline code. You can also assign an optional name to the offline access code. For more details, see the Create Access Code endpoint.

Request:

# Get the device.
device = seam.locks.get(
  device_id="11111111-1111-1111-1111-444444444444"
)

# Confirm that the device supports offline access codes.
if device.can_program_offline_access_codes:
  # Create the hourly-bound offline access code.
  seam.access_codes.create(
    device_id = device.device_id,
    name = "my hourly-bound offline code",
    starts_at = "2023-11-10T00:00:00-00:00",
    ends_at = "2023-11-15T18:00:00-00:00",
    is_offline_access_code = True
  )

Response:

AccessCode(
  access_code_id='11111111-1111-1111-1111-777777777777',
  device_id='11111111-1111-1111-1111-444444444444',
  type='time_bound',
  starts_at='2023-11-10T00:00:00.000Z',
  ends_at='2023-11-15T18:00:00.000Z',
  name='my hourly-bound offline code',
  is_offline_access_code=True,
  ...
)

2. Verify Successful Time-Bound Code Registration

The lifecycle of a time-bound access code is marked by distinct phases:

  1. Unset: When initially created on Seam, the offline access code remains in an unset state, indicating that it is not yet available for use on the lock due to a configured future activation time.

  2. Setting: As the scheduled starts_at time approaches, Seam initiates the process of readying the code for use on the lock, transitioning the status of the offline code to setting.

  3. Set: Upon successful programming, the status updates to set, signaling that the code is ready to grant the designated user the ability to unlock the door.

There are two methods to verify that an time-bound offline access code has been registered in the offline access code server that the device manufacturer maintains:

  • Polling: Continuously query the access code until the status is updated. For instructions, see Polling Method.

  • Webhook: Wait for updates to arrive using webhook requests from the Seam API. For instructions, see Webhook Events Method.

Program a Daily-Bound Offline Access Code

To create a daily-bound offline access code, first issue a creation request. Then, poll or use a webhook to confirm the successful code registration in the offline access code server that the device manufacturer maintains.

1. Create a Daily-Bound Access Code

To create a daily-bound offline access code, provide the device_id of the lock for which you want to create the code and set is_offline_access_code to true. Specify the starts_at and ends_at ISO 8601 timestamps to define the active time window for the offline code. For a daily-bound offline access code, you must specify the same time (but not the same date) in the starts_at and ends_at properties.

Because daily-bound offline access codes require day-level duration granularity, you can also set max_time_rounding to 1day (or 1d), instead of the default 1hour (or 1h). Note that the Seam API returns an error if max_time_rounding is 1hour and the necessary rounding amount exceeds one hour.

You can also assign an optional name to the offline access code. For more details, see the Create Access Code endpoint.

Request:

# Get the device.
device = seam.locks.get(
  device_id="11111111-1111-1111-1111-444444444444"
)

# Confirm that the device supports offline access codes.
if device.can_program_offline_access_codes:
  # Create the daily-bound offline access code.
  seam.access_codes.create(
    device_id = device.device_id,
    name = "my daily-bound offline code",
    starts_at = "2023-11-17T00:00:00-00:00",
    ends_at = "2023-12-18T00:00:00-00:00",
    max_time_rounding = "1d",
    is_offline_access_code = True
  )

Response:

AccessCode(
  access_code_id='11111111-1111-1111-1111-888888888888',
  device_id='11111111-1111-1111-1111-444444444444',
  type='time_bound',
  starts_at='2023-11-17T00:00:00.000Z',
  ends_at='2023-12-18T00:00:00.000Z',
  name='my daily-bound offline code',
  is_offline_access_code=True,
  ...
)

2. Verify Successful Time-Bound Code Registration

The lifecycle of a time-bound access code is marked by distinct phases:

  1. Unset: When initially created on Seam, the offline access code remains in an unset state, indicating that it is not yet available for use on the lock due to a configured future activation time.

  2. Setting: As the scheduled starts_at time approaches, Seam initiates the process of readying the code for use on the lock, transitioning the status of the offline code to setting.

  3. Set: Upon successful programming, the status updates to set, signaling that the code is ready to grant the designated user the ability to unlock the door.

There are two methods to verify that an time-bound offline access code has been registered in the offline access code server that the device manufacturer maintains:

  • Polling: Continuously query the access code until the status is updated. For instructions, see Polling Method.

  • Webhook: Wait for updates to arrive using webhook requests from the Seam API. For instructions, see Webhook Events Method.


Creating One-Time-Use Offline Access Codes

For igloohome locks, you can create one-time-use offline access codes that are valid for 24 hours from the starts_at date and time that you configure. These codes expire after a single use. To confirm that your device supports one-time-use offline access codes, see the corresponding device guide.

To create a one-time-use offline access code, first issue a creation request. In this request, set is_offline_access_code and is_one_time_use to true, and specify the desired starts_at date and time. Then, poll or use a webhook to confirm the successful code registration in the offline access code server that the device manufacturer maintains.

1. Create a One-Time-Use Offline Access Code

To create a one-time-use offline access code, provide the device_id of the lock for which you want to create the code. Set is_offline_access_code and is_one_time_use to true. Specify the starts_at ISO 8601 timestamp to define the beginning of the active time window for the offline code.

You can also assign an optional name to the offline access code. For more details, see the Create Access Code endpoint.

Request:

# Get the device.
device = seam.locks.get(
  device_id="11111111-1111-1111-1111-444444444444"
)

# Confirm that the device supports offline access codes.
if device.can_program_offline_access_codes:
  # Create the one-time-use offline access code.
  seam.access_codes.create(
    device_id = device.device_id,
    name = "my one-time-use offline code",
    starts_at = "2023-11-12T00:00:00-00:00",
    is_offline_access_code = True,
    is_one_time_use = True
  )

Response:

AccessCode(
  access_code_id='11111111-1111-1111-1111-777777888888',
  device_id='11111111-1111-1111-1111-444444444444',
  type='time_bound',
  starts_at='2023-11-12T00:00:00.000Z',
  name='my one-time-use offline code',
  is_offline_access_code=True,
  is_one_time_use=True,
  ...
)