Programming Offline Access Codes on Dormakaba Oracode Locks

Dormakaba Oracode locks use offline access codes (PIN codes) that are generated remotely and work without requiring the lock to be online. This guide explains how to create these codes and the requirements you need to understand.

Understanding Oracode offline access codes

Offline access codes are PIN codes generated by Seam that work on the lock without an internet connection. Dormakaba maintains a server-based registry of synchronized encryption keys that enable these codes to work offline.

Once generated, you can share these codes with guests through messaging or your property management system—guests don't need to install any special app to unlock the door.

Before you create codes

Time slot requirements (Required)

Dormakaba Oracode locks require predefined time slots (also called "user levels") to create access codes. You cannot create codes with arbitrary check-in/check-out times.

What are time slots?

Time slots define check-in and check-out times of day that are pre-configured by your Dormakaba installer. For example, a "4:00 PM → 10:00 AM" slot can be used for any booking that checks in at 4:00 PM and checks out at 10:00 AM, regardless of how many nights the guest stays.

How Seam matches your bookings:

When you create an access code, Seam automatically rounds your booking times (within 1 hour) to match an available time slot. The access code will use the time slot's times, not your exact booking times.

Example:

Your booking: 3:45 PM → 10:15 AM
Available slot: 4:00 PM → 10:00 AM
Result: Code created for 4:00 PM → 10:00 AM ✓

If your booking times are more than 1 hour away from any configured slot, code creation will fail.

Retrieving available time slots

Before creating access codes, check which time slots are configured for your device:

# Get device and time slots
device = seam.devices.get(device_id="your-device-id")
time_slots = device.properties
    .get("dormakaba_oracode_metadata", {})
    .get("predefined_time_slots", [])

print(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
  },
  ...
]

// Get device and time slots
const device = await seam.devices.get({
  device_id: "your-device-id"
});

const timeSlots = device.properties.dormakaba_oracode_metadata?
  .predefined_time_slots || [];

console.log(timeSlots)
print(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
  },
  ...
]

Understanding time slot format:

Time slots use Seam's Time of Day (TOD) format: 15:30:00-08:00[America/Los_Angeles]

15:30:00 - Hour and minute (3:30 PM)
-08:00 - UTC offset
[America/Los_Angeles] - IANA timezone

Time slot properties:

Each time slot includes:

name: Display name (e.g., "Guest Standard 4pm-10am")
check_in_time: Check-in time in TOD format
check_out_time: Check-out time in TOD format
is_24_hour: Whether this is a daily-bound slot
is_biweekly_mode: Whether this uses biweekly scheduling
is_one_shot: Whether code expires after first use (not currently supported)
is_master: Whether this provides master access (not currently supported)

For detailed guidance on configuring time slots, see our Time Slot Configuration Guide.

Other important limitations

Duration limit: Access codes can be valid for a maximum of 31 consecutive days.

Cannot be updated or deleted: Dormakaba Oracode access codes cannot be modified after creation. Be mindful of device-specific code limits when creating large numbers of codes.

Time zone considerations: All times must be in the lock's local time zone. When creating codes, use the time and offset that match the lock's configured time zone (e.g., 2024-09-10T16:00:00-07:00 for Pacific time).

View device timezone:

# Python
device = seam.devices.get(device_id="your-device-id")
timezone = device.properties.get("dormakaba_oracode_metadata", {}).get("iana_timezone")
print(f"Device timezone: {timezone}")

Creating hourly-bound access codes

Hourly-bound codes let you specify exact check-in and check-out times (within the constraints of available time slots).

Step 1: Create the access code

Provide the device_id, set is_offline_access_code to true, and specify starts_at and ends_at timestamps. Make sure these times match a configured time slot on the device (within 1 hour tolerance).

Python example:

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

# Confirm offline access code support
if device.can_program_offline_access_codes:
  # Create the code
  access_code = seam.access_codes.create(
    device_id=device.device_id,
    name="Guest - Room 101",
    starts_at="2024-09-10T16:00:00-07:00",  # Must match lock's timezone
    ends_at="2024-09-15T10:00:00-07:00",
    is_offline_access_code=True
  )
  
  print(f"Code created: {access_code.code}")
  print(f"Status: {access_code.status}")

Step 2: Verify the code was set

Access codes go through three lifecycle phases:

Unset: Code created but not yet active
Setting: Seam is registering the code with Dormakaba's server
Set: Code is ready to use

Option A: Polling method

import time

# Poll until status is 'set'
access_code = seam.access_codes.get(access_code_id="your-code-id")
while access_code.status != "set":
  time.sleep(1)
  access_code = seam.access_codes.get(access_code_id=access_code.access_code_id)
  
print(f"Code ready! PIN: {access_code.code}")

Option B: Webhook method

Subscribe to access_code.set_on_device webhook events to receive notifications when codes are ready.

Creating daily-bound access codes

Daily-bound codes are useful when you need day-level granularity and want more flexible rounding.

Step 1: Create the access code

For daily-bound codes, specify the same time (but different dates) in starts_at and ends_at. You can also set max_time_rounding to 1day to allow Seam to round up to a full day to match available slots.

# Create daily-bound code
access_code = seam.access_codes.create(
  device_id=device.device_id,
  name="Guest - Room 101",
  starts_at="2024-09-16T00:00:00-07:00",
  ends_at="2024-09-18T23:59:00-07:00",
  max_time_rounding="1d",  # Allow day-level rounding
  is_offline_access_code=True
)

print(f"Code created: {access_code.code}")

// Create daily-bound code
const accessCode = await seam.accessCodes.create({
  device_id: device.device_id,
  name: "Guest - Room 101",
  starts_at: "2024-09-16T00:00:00-07:00",
  ends_at: "2024-09-18T23:59:00-07:00",
  max_time_rounding: "1d",  // Allow day-level rounding
  is_offline_access_code: true
});

console.log(`Code created: ${accessCode.code}`);

Step 2: Verify the code was set

Use the same polling or webhook methods as hourly-bound codes to confirm the code is ready.

Troubleshooting

"No time slots found" error

This means your booking times don't match any configured time slot within the 1-hour tolerance.

Check what's configured:

# List all time slots for debugging
device = seam.devices.get(device_id="your-device-id")
time_slots = device.properties.get("dormakaba_oracode_metadata", {}).get("predefined_time_slots", [])

if not time_slots:
    print("❌ No time slots configured on this device")
else:
    print(f"✓ {len(time_slots)} time slots configured:")
    for slot in time_slots:
        print(f"  • {slot['name']}")
        print(f"    Check-in: {slot['check_in_time']}")
        print(f"    Check-out: {slot['check_out_time']}")

Solutions:

Adjust your booking times to be within 1 hour of an available slot
Contact your Dormakaba installer to add time slots matching your booking patterns

Code creation fails silently

This typically happens with automated systems. Verify that:

Time slots are configured for the door
Booking times are within 1 hour of a configured slot
The device supports offline access codes (can_program_offline_access_codes is true)

Different behavior on different doors

Time slots are configured per door. Check each device individually:

python

# Check all devices in an account
devices = seam.devices.list(connected_account_id="your-account-id")

for device in devices:
    time_slots = device.properties.get("dormakaba_oracode_metadata", {}).get("predefined_time_slots", [])
    print(f"{device.properties.get('name')}: {len(time_slots)} time slots")
    
    if not time_slots:
        print(f"  ⚠️ WARNING: No time slots configured!")

Best practices

Always check for time slots first: Before attempting to create codes, verify that time slots are configured on the device.

Plan your time slots carefully: Work with your installer to configure time slots that match your most common booking patterns. Include a 24-hour slot (12:00 PM → 12:00 PM) for maximum flexibility.

Test before going live: After your installer configures time slots, wait 30 minutes for Seam to sync, then create test codes to verify everything works.

Monitor code limits: Since codes cannot be deleted, be aware of your device's code limit to avoid reaching capacity.

Use consistent naming: Include meaningful names for codes (e.g., "Guest - Room 101 - Sept 10-15") to help with tracking and troubleshooting.

Need help?

For time slot configuration: Contact your Dormakaba installer
For Seam API questions: [email protected]
For detailed time slot guidance: See our Time Slot Configuration Guide

PreviousGet started with dormakaba Oracode Locks Nextecobee Thermostats

Last updated 3 days ago

Was this helpful?