Comment on page
Lifecycle of Access Codes
Learn how access codes transition between states, and the corresponding events that are emitted.
Programming access codes involves asynchronous processes, which can be complex to manage. Such asynchronous flows depend on interactions with smart devices and third-party applications outside your main application. Our access code API streamlines this process by tracking the status of the access code using a state machine.
The Access Code flow begins you makes a request to create an access code on Seam.
Lifecycle of an access code
This is the initial state of an access code. At this stage, the code is created in the system but has not yet been sent to or recognized by the smart device. It's essentially in a queue, waiting for its turn to be programmed.
For natively-scheduled codes, Seam will preload the access code onto the device 72 hours ahead of the
starts_attime. Seam will also emit an
access_code.scheduled_on_deviceevent, which indicates a natively-scheduled code has been programmed on the device, and is awaiting its designated activation time. You'll observe that the access code remains in an
unsetstate until the
starts_attime, at which point it will activate and transition to the
For Just-in-time codes, once the code starts being programmed onto the smart device, it transitions to the
settingstate. During this phase, Seam is actively trying to communicate with the smart device to program the code.
For natively-scheduled codes, if there's an issue programming the natively-scheduled code by its
starts_attime, then the code's status will display as
Once an access code is successfully programmed onto a smart device, specific events are emitted to indicate its status. For standard access codes, the
access_code.set_on_deviceevent is triggered, signifying successful programming. Regardless of the type, the code is securely stored in the device's memory. However, its immediate usability may be contingent on properties like
starts_at. For natively scheduled codes, you can expect the
access_code.set_on_deviceevent to be emitted when the
starts_atactivation time is reached.
When an access code is no longer required or its
ends_attime has been reached, Seam initiates the process to remove the code from the device. The access code then transitions to the "removing" state. During this period, the system actively communicates with the smart device, working to erase the access code from its memory.
When an access code is removed from a device, it's not just deleted from the device's memory. Correspondingly, the access code object is also deleted from Seam's database. As a result, if you try to retrieve that specific access code through the 'get access code' endpoint afterwards, you will encounter a 404 error, indicating that the code no longer exists.
Seam is modifying the behavior of access codes so they won't return a 404 error unless explicitly deleted by the API user. Currently, access codes yield a 404 error when removed from a device, such as when a time-bound access code expires.
Beyond the states previously detailed, an "unknown" state exists. This state suggests that the account has been disconnected, preventing Seam from interfacing with the third-party API to verify the access code.