Managing Backup Access Codes

Learn how to bullet proof your access code implementation with back up access codes.

A backup access code pool is a collection of pre-programmed access codes stored on a device, ready for use. These codes are programmed in addition to the regular access codes on Seam, serving as a safety net for any issues with the primary codes.

If there's ever a complication with a primary access code—be it due to intermittent connectivity, manual removal from a device, or provider outages—a backup code can be retrieved. Its end time can then be adjusted to align with the original code, facilitating seamless and uninterrupted access.

To bulletproof your implementation of access codes, it's essential to maintain a pool of backup access codes for each device. Seam provides a robust implementation of this backup pool system, and this article will help you learn how to use our backup access pool system.

---

Before You Begin

To confirm that Seam supports back up code pools for your device, check the device's properties by inspecting the response from Get Device or List Devices. Ensure that the device's properties.supports_backup_access_code_pool is true.

After you've done that, come back here and keep reading.

Example Payload:

{
    "device_id": "00000000-0000-0000-0000-000000000000",
    "properties": {
        "supports_backup_access_code_pool": true,
        ...
    },
    ...
}

Python

Request:

device = seam.devices.get("6aae9d08-fed6-4ca5-8328-e36849ab48fe")
pprint("Supports backup access code pool: "
    + str(device.properties.supports_backup_access_code_pool))

Response:

'Supports backup access code pool: True'

cURL (bash)

JavaScript

Ruby

PHP

C#

Java

---

Enabling and Retrieving Backup Codes

1. Activate the backup access code pool

To activate the backup pool, set use_backup_access_code_pool to true when creating an access code. After activation, the backup access code pool cannot be turned off for that device. However, if you unmanage the device, any backup access codes are removed.

This activation is a one-time process for each device. Once initiated, Seam consistently maintains a backup code pool for the device. All access codes associated with the device utilize the same backup code pool.

In the smart lock app, backup access codes appear as "Backup {CODE_ID} (Seam)".

Python

Request:

device_id = "6aae9d08-fed6-4ca5-8328-e36849ab48fe"

created_access_code = seam.access_codes.create(
  device = device_id,
  name = "my time-bound code",
  starts_at = "2025-01-01T16:00:00Z",
  ends_at = "2025-01-22T12:00:00Z",
  use_backup_access_code_pool = True
)

pprint(created_access_code)

Response:

AccessCode(access_code_id='dc83d82d-55d2-4178-8c8c-10382311aed2',
           device_id='6aae9d08-fed6-4ca5-8328-e36849ab48fe',
           type='time_bound',
           code='9132',
           created_at='2023-10-19T05:07:03.693Z',
           errors=[],
           warnings=[],
           starts_at='2025-01-01T16:00:00.000Z',
           ends_at='2025-01-22T12:00:00.000Z',
           name='my time-bound code',
           status='unset',
           common_code_key=None,
           is_managed=True,
           is_waiting_for_code_assignment=None,
           is_scheduled_on_device=False,
           pulled_backup_access_code_id=None,
           is_backup_access_code_available=True,
           is_backup=None,
           appearance=None,
           is_external_modification_allowed=False)

cURL (bash)

JavaScript

Ruby

PHP

C#

Java

2. Detect when an access code has failed to program

When you receive an access_code.failed_to_set_on_device event through your Webhook, or notice a failed_to_set_on_device error on the access code object, that means that the access code has failed to program.

You can retrieve a backup access code to use instead.

3. Confirm the availability of a backup access code

To confirm that a backup access code is available for retrieval, check the is_backup_access_code_available property on the access code by inspecting the response from Get Access Code or List Access Codes. If the backup code pool has been exhausted, this property returns false.

Note that we only support pulling backup codes for time_bound codes at this time.

Python

Request:

access_code = seam.access_codes.get("dc83d82d-55d2-4178-8c8c-10382311aed2")

pprint("Is backup access code available: "
    + str(access_code.is_backup_access_code_available))

Response:

'Is backup access code available: True'

cURL (bash)

JavaScript

Ruby

PHP

C#

Java

4. Retrieve a backup access code

To retrieve a backup access code for an access code, include the access_code_id in the Pull Backup Access Codes request. In the response, you receive the new backup access code. Be sure to share the new backup PIN code with the user of the original access code.

Upon executing this action, Seam performs the following additional actions:

• Mark the backup access code as pulled ("pulled": true), meaning that it has been removed from the pool.

• Associate the backup access code with the original access code, ensuring that any future requests to the Pull Backup Access Code request return the same backup access code.

• Update the ends_at date for the backup access code to match that of the original access code.

• Attempt to refill the backup access code pool with a new backup code.

Python

Request:

access_code_id = "dc83d82d-55d2-4178-8c8c-10382311aed2"

backup_code = seam.access_codes.pull_backup_access_code(
    access_code = access_code_id
)

pprint(backup_code)

Response:

AccessCode(access_code_id='6db16e34-48d4-467a-856c-32a56b9cf0da',
           device_id='6aae9d08-fed6-4ca5-8328-e36849ab48fe',
           type='time_bound',
           code='7768',
           created_at='2023-10-19T05:07:05.548Z',
           errors=[],
           warnings=[],
           starts_at='2023-10-19T05:22:37.082Z',
           ends_at='2025-01-22T12:00:00.000Z',
           name='Backup 6db16e34-48d4-467a-856c-32a56b9cf0da (Seam)',
           status='set',
           common_code_key=None,
           is_managed=True,
           is_waiting_for_code_assignment=None,
           is_scheduled_on_device=None,
           pulled_backup_access_code_id=None,
           is_backup_access_code_available=False,
           is_backup=True,
           appearance={'first_name': 'Backup',
                       'last_name': '6db16e34-48d4-467a-856c-32a56b9cf0da '
                                    '(Seam)',
                       'name': 'Backup 6db16e34-48d4-467a-856c-32a56b9cf0da '
                               '(Seam)'},
           is_external_modification_allowed=False)

cURL (bash)

JavaScript

Ruby

PHP

C#

Java

---

Troubleshooting

When you have the backup access code pool feature enabled for a device, be on the lookout for the following warnings and errors on the device:

Warning: many_active_backup_codes

Multiple back up codes have been pulled from the device. This usually indicates that Seam is having issues programming access codes onto the device. Check if the device is offline or if there are other issues.

Warning: partial_backup_access_code_pool

Seam is having trouble refilling the back up access code pool. This could result from device connection issues or from the device running out of space for new codes.

Error: empty_backup_access_code_pool

There are no more back up codes available in the pool. This can happen when you've just enabled the back up pool feature, or when all of the backup access codes have been used.

---

Supported Brands

All door locks with the access_code capability are expected to support this feature, with the exception of Lockly and Salto locks.