Creating dormakaba Oracode Offline Access Codes
Learn how to create dormakaba Oracode offline access codes, including understanding manufacturer-specific requirements.
The Seam integration for dormakaba Oracode enables you to manage offline access codes for dormakaba Oracode locks. You generate offline access (PIN) codes remotely, and the manufacturer maintains a server-based registry of synchronized encryption keys (tokens) to enable these offline codes. Then, owners or managers can share these codes with users through messaging or other similar applications, and the users do not need to install a special application to unlock the device.
To learn about the special requirements regarding offline access codes for dormakaba Oracode locks, see Offline Access Code Requirements. For more information about using offline access codes, see Offline Access Codes and Managing Offline Access Codes.
Offline Access Code Requirements
Seam supports daily-bound and hourly-bound offline access codes for dormakaba Oracode locks. Note the following dormakaba Oracode-specific restrictions and requirements for offline access codes:
Duration
The duration limit for a dormakaba Oracode offline access code is 31 consecutive days.
Deletion and Access Code Limits
You cannot delete dormakaba Oracode offline access codes. Consequently, it is important to be aware of device- and installation-specific access code limits, especially if you plan to create large numbers of codes simultaneously. For more information about these limits, see the user manual for your dormakaba Oracode lock or contact your dormakaba Oracode support representative.
User Levels
dormakaba Oracode locks use pre-programmed sets of access code time slots called "user levels" or "user prefixes." All the access codes in a specific user level have the same prefix, for example, 123
in 123456789
and 123987654
. Further, all access codes in a specific user level use the same configuration for the following characteristics:
Check in and check out time
Whether the access code is a one-time-use code
Whether the access code is daily-bound (
is_24_hour
)Whether the access code is a biweekly code (that is, a code that is valid for two weeks)
Whether the access code is a master code that exists indefinitely, for example, for site owners
When you create a dormakaba Oracode offline access code, you must set the duration of the code to match—exactly—one of the time slots on the device. To view a list of all available time slots for a specific device, get the device and view the device.properties.dormakaba_oracode_metadata.predefined_time_slots
property for the device.
"predefined_time_slots": [
{
"name": "Guest RCI D 7am-7pm",
"prefix": 0,
"is_master": false,
"is_24_hour": false,
"is_one_shot": false,
"check_in_time": "07:00:00[America/Los_Angeles]",
"check_out_time": "19:00:00[America/Los_Angeles]",
"is_biweekly_mode": false,
"dormakaba_oracode_user_level_id": "f23721ec-6dce-4c54-8971-40d58449a366",
"ext_dormakaba_oracode_user_level_prefix": 0
},
...
]
Time Zones
All time zone configuration and display for dormakaba Oracode locks occur in the local time zone of the lock, itself. When you connect your dormakaba Oracode site to Seam initially, you specify the time zone in which the site is located. Consequently, when you configure an access code for a dormakaba Oracode lock, you set the starts_at
and ends_at
properties using a time and offset that match the local time zone of the lock.
For example, suppose that your lock includes the following user level:
"check_in_time": "07:00:00[America/Los_Angeles]",
"check_out_time": "19:00:00[America/Los_Angeles]"
To set an access code that uses this user level, set the times for the starts_at
and ends_at
properties as follows:
"starts_at": "2024-09-10T07:00:00-07:00",
"ends_at": "2024-09-15T19:00:00-07:00"
View the Time Zone of a dormakaba Oracode Lock
To view the local time zone of a dormakaba Oracode lock, get the device and see the check_in_time
and check_out_time
within each time slot in the device.properties.dormakaba_oracode_metadata.predefined_time_slots
property for the device. You can also see the local time zone for a dormakaba Oracode lock in the dormakaba_oracode_device_metadata.iana_timezone
property.
Master Codes
Seam does not currently support dormakaba Oracode master offline access codes.
One-Time-Use Codes
Seam does not currently support dormakaba Oracode one-time-use offline access codes.
Programming dormakaba Oracode Offline Access Codes
You can create hourly- and daily-bound offline access codes for dormakaba Oracode devices.
Hourly-Bound Offline Access Codes
To create an hourly-bound offline access code, issue an access code creation request. Then, poll or use a webhook to confirm that the code was registered successfully in the dormakaba Oracode offline access code server.
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. Make sure to set the duration of the code to match—exactly—one of the user levels on the device. 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",
# Make sure that the validity period matches
# a user level for the device.
starts_at = "2024-09-10T07:00:00-07:00",
ends_at = "2024-09-15T19:00:00-07: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='2024-09-10T14:00:00.000Z',
ends_at='2024-09-16T02: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:
Unset
: When initially created on Seam, the offline access code remains in anunset
state, indicating that it is not yet available for use on the lock due to a configured future activation time.Setting
: As the scheduledstarts_at
time approaches, Seam initiates the process of readying the code for use on the lock, transitioning thestatus
of the offline code tosetting
.Set
: Upon successful programming, the status updates toset
, 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.
Daily-Bound Offline Access Codes
To create a daily-bound offline access code, first issue a creation request. Then, poll or use a webhook to confirm that the code was registered successfully in the dormakaba Oracode offline access code server.
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. Make sure to set the duration of the code to match—exactly—one of the user levels on the device. 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",
# Make sure that the validity period matches
# a user level for the device.
starts_at = "2024-09-16T00:00:00-07:00",
ends_at = "2024-09-18T23:59:00-07: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='2024-09-16T07:00:00.000Z',
ends_at='2024-09-19T06:59: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:
Unset
: When initially created on Seam, the offline access code remains in anunset
state, indicating that it is not yet available for use on the lock due to a configured future activation time.Setting
: As the scheduledstarts_at
time approaches, Seam initiates the process of readying the code for use on the lock, transitioning thestatus
of the offline code tosetting
.Set
: Upon successful programming, the status updates toset
, 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.
Last updated
Was this helpful?