# Event types in Nebula ## Overview Events allow you to see activity that is taking place within your installation. For example, these could be events which indicate which access points are being unlocked and by whom. Certain events also include information about the **actor** - the principal entity (such as a manager or service account) that initiated or performed the action associated with the event. This provides audit trail information about who made changes to your system. This section aims to detail the types of events that are currently available in the Nebula API. We may add more at any time, so in developing and maintaining your code, you should not assume that only these types exist. See also the [documentation for the events service](/nebula/api/salto/nebula/event/v1). ## Common use cases The events service is useful any time your integration needs to react to or record activity in an installation. Common scenarios include: - **Real-time access monitoring** - subscribe to door unlock and lock events to track which access points are being used and by whom. - **Audit trails / Activity** - track who created, modified, or deleted users, access rights, and units, including the actor responsible for each change. - **Access denied analysis** - monitor failed access attempts and the reasons behind them to identify misconfigured permissions or expired credentials. ## Event timestamps Each event has two timestamps: - **`occur_time`** - when the physical event actually took place (for example, when the credential was presented at the reader). - **`create_time`** - when the event record was received and recorded by the system. These are not the same. For online access points, there is typically a 1-3 second lag between `occur_time` and `create_time`. However, for standalone (offline) locks using card keys, the lag can be longer - potentially hours or days - as events are stored locally on the device and only forwarded to the system when the device next syncs via an online access point. When filtering events by time - for example, to identify who triggered a door open within a specific window - always filter on `occur_time`. Filtering on `create_time` can cause you to miss events that occurred just before your query window opened. ## Privacy settings and event visibility {{% info-panel %}} **Unit privacy affects event availability.** If a unit has privacy enabled, events associated with users in that unit are not transmitted via the API. Integrations that rely on access events to trigger downstream actions must account for this: if a user belongs to a privacy-enabled unit, no event will be returned for their activity. See [unit privacy](https://support.saltosystems.com/homelok/user-guide/property-manager/units/privacy/) for more information. {{% /info-panel %}} ## Event types You'll notice that these events generally follow the pattern: `{{resource}}{{event}}`. For example: `accesspointcreated`. Our goal is to design a consistent system that makes things easier to anticipate and code against. ### List of events All event type names use the [fully qualified name](https://en.wikipedia.org/wiki/Fully_qualified_name). #### `com.saltosystems.nebula.event.v1.accesspointcreated` Event representing the creation of an {{< glossary_term "access_point" >}}access point{{< /glossary_term >}}. Includes the access point that was created and the actor who created it. #### `com.saltosystems.nebula.event.v1.accesspointupdated` Event representing the update of an access point. Includes the access point that was updated and the actor who updated it. #### `com.saltosystems.nebula.event.v1.accesspointdeleted` Event representing the deletion of an access point. Includes the access point that was deleted and the actor who deleted it. #### `com.saltosystems.nebula.event.v1.accesspointunlocked` Event representing the unlocking of an access point. Includes the access point that's been unlocked: `salto.nebula.accesspoint.v1.AccessPoint` and the user who unlocked the access point: `salto.nebula.user.v1.User`. For user unlocking, the event includes the credential type used to unlock the access point. The following credential types are available: - `salto.nebula.emergencykey.v1.EmergencyKey` - `salto.nebula.user.v1.CardKey` - `salto.nebula.user.v1.AppKey` - `salto.nebula.user.v1.WalletKey` - `salto.nebula.user.v1.Passcode` The event also includes a `direction` field that indicates the direction of passage: - `DIRECTION_UNSPECIFIED` - Direction is not specified (used for remote opening) - `ENTRY` - Credential used to gain access from outside to inside - `EXIT` - Credential used to leave from inside to outside {{% info-panel %}} [Remote unlocking](https://developer.saltosystems.com/nebula/api/salto/nebula/accesspoint/v1/#unlock-an-access-point) uses `DIRECTION_UNSPECIFIED` and does not include a credential type. {{% /info-panel %}} #### `com.saltosystems.nebula.event.v1.accesspointlocked` Event representing the locking of an access point. Includes the access point that's been locked: `salto.nebula.accesspoint.v1.AccessPoint` and the user who locked the access point `salto.nebula.user.v1.User`. For user locking, the event includes the credential type used to lock the access point. The following credential types are available: - `salto.nebula.emergencykey.v1.EmergencyKey` - `salto.nebula.user.v1.CardKey` - `salto.nebula.user.v1.AppKey` - `salto.nebula.user.v1.WalletKey` - `salto.nebula.user.v1.Passcode` #### `com.saltosystems.nebula.event.v1.accesspointforcedopen` {{% label type="beta" %}} Event representing a forced open of an access point. That's to say, the access point has been unlocked without using a valid key. #### `com.saltosystems.nebula.event.v1.accesspointclosed` Event representing the closing of an access point. This event might not be triggered with all access point closures. #### `com.saltosystems.nebula.event.v1.accessdenied` Event representing a denied access to a user by an access point or controller. Includes the source that denied access (either `salto.nebula.accesspoint.v1.AccessPoint` or `salto.nebula.controller.v1.Controller`) and the user whose access was rejected: `salto.nebula.user.v1.User`. The event also includes a `reason` field that indicates why access was denied. The following reasons are available: - `REASON_UNSPECIFIED` - The reason is not specified. - `CREDENTIAL_EXPIRED` - The presented credential has expired and is no longer valid. - `CREDENTIAL_UNACTIVATED` - The provided key is not yet activated. The key's activation date and time are scheduled for a future moment. - `CREDENTIAL_PERMISSION_INSUFFICIENT` - The provided credential does not have the required permission. - `CREDENTIAL_PERMISSION_OUTSIDE_VALIDITY` - The provided credential is permitted within the allowed schedule but the permission is not activated at this time. - `CREDENTIAL_PERMISSION_OUTSIDE_SCHEDULE` - The provided credential is not permitted within the allowed schedule. - `INVALID_ACCESS_CODE` - The provided access code is invalid. Access codes are numeric passcodes entered by users on a device keypad to gain access. - `DEVICE_BATTERY_INSUFFICIENT` - The device at which the credential was presented has insufficient battery level and cannot process the access request. For user access attempts, the event includes the credential type used to attempt access. The following credential types are available: - `salto.nebula.emergencykey.v1.EmergencyKey` - `salto.nebula.user.v1.CardKey` - `salto.nebula.user.v1.AppKey` - `salto.nebula.user.v1.WalletKey` - `salto.nebula.user.v1.Passcode` #### `com.saltosystems.nebula.event.v1.accesspointleftopen` {{% label type="beta" %}} Event representing the detection of an access point that's been left open. #### `com.saltosystems.nebula.event.v1.accessrightcreated` Event representing the creation of an {{< glossary_term "access_right" >}}access right{{< /glossary_term >}}. Includes the access right that was created and the actor who created it. #### `com.saltosystems.nebula.event.v1.accessrightupdated` Event representing the update of an access right. Includes the access right that was updated and the actor who updated it. #### `com.saltosystems.nebula.event.v1.accessrightdeleted` Event representing the deletion of an access right. Includes the access right that was deleted and the actor who deleted it. #### `com.saltosystems.nebula.event.v1.accessrightaccesspointcreated` Event representing the creation of an access right's access point association. Includes the creation of the access point's access right association: `salto.nebula.accessright.v1.AccessRight` and the Access right's access point association: `salto.nebula.accesspoint.v1.AccessPoint`, as well as the actor who created it. #### `com.saltosystems.nebula.event.v1.accessrightaccesspointdeleted` Event representing the deletion of an access right's access point association. Includes the deletion of the access point's access right association: `salto.nebula.accessright.v1.AccessRight` and the access right's access point association: `salto.nebula.accesspoint.v1.AccessPoint`, as well as the actor who deleted it. #### `com.saltosystems.nebula.event.v1.accessrightaccesspointsbatchcreated` Event representing the creation of multiple access right's access points association. Includes the actor who created them. #### `com.saltosystems.nebula.event.v1.accessrightaccesspointsbatchdeleted` Event representing the deletion of multiple access right's access point association. Includes the actor who deleted them. #### `com.saltosystems.nebula.event.v1.usercreated` Event representing the creation of a user. Includes the user that was created and the actor who created it. #### `com.saltosystems.nebula.event.v1.userupdated` Event representing the update of a user. Includes the user that was updated and the actor who updated it. #### `com.saltosystems.nebula.event.v1.userblocked` Event representing the blocking of a user. Includes the user that was blocked and the actor who blocked them. See more on [blocking and unblocking users in the user guide](https://support.saltosystems.com/homelok/user-guide/property-manager/users/block-users). #### `com.saltosystems.nebula.event.v1.userunblocked` Event representing the unblocking of a user. Includes the user that was unblocked and the actor who unblocked them. See more on [blocking and unblocking users in the user guide](https://support.saltosystems.com/homelok/user-guide/property-manager/users/block-users). #### `com.saltosystems.nebula.event.v1.userdeleted` Event representing the deletion of a user. Includes the user that was deleted and the actor who deleted it. #### `com.saltosystems.nebula.event.v1.useraccessrightcreated` Event representing the creation of a user's access right association. Includes the access right's user association: `salto.nebula.user.v1.User` and the user's access right association: `salto.nebula.accessright.v1.AccessRight`, as well as the actor who created it. #### `com.saltosystems.nebula.event.v1.useraccessrightupdated` Event representing the update of a user's access right association. Includes the access right's user association: `salto.nebula.user.v1.User` and the user's access right association: `salto.nebula.accessright.v1.AccessRight`, as well as the actor who updated it. #### `com.saltosystems.nebula.event.v1.useraccessrightdeleted` Event representing the deletion of a user's access right association. Includes the access right's user association: `salto.nebula.user.v1.User` and the user's access right association: `salto.nebula.accessright.v1.AccessRight`, as well as the actor who deleted it. #### `com.saltosystems.nebula.event.v1.cardkeyassigned` Event representing the assignment of a user's {{< glossary_term "card_key" >}}card key{{< /glossary_term >}}. Includes the card key's user: `salto.nebula.user.v1.User` and the card key assigned: `salto.nebula.user.v1.CardKey`, as well as the actor who assigned it. #### `com.saltosystems.nebula.event.v1.cardkeycanceled` Event representing the cancelation of a user's {{< glossary_term "card_key" >}}card key{{< /glossary_term >}}. Includes the card key's user: `salto.nebula.user.v1.User` and the card key canceled: `salto.nebula.user.v1.CardKey`, as well as the actor who canceled it. #### `com.saltosystems.nebula.event.v1.appkeyassigned` Event representing the assignment of a user's {{< glossary_term "app_key" >}}app key{{< /glossary_term >}}. Includes the app key's user: `salto.nebula.user.v1.User` and the app key assigned: `salto.nebula.user.v1.AppKey`, as well as the actor who assigned it. #### `com.saltosystems.nebula.event.v1.appkeycanceled` Event representing the cancelation of a user's {{< glossary_term "app_key" >}}app key{{< /glossary_term >}}. Includes the app key's user: `salto.nebula.user.v1.User` and the app key canceled: `salto.nebula.user.v1.AppKey`, as well as the actor who canceled it. #### `com.saltosystems.nebula.event.v1.walletkeyassigned` Event representing the assignment of a user's {{< glossary_term "apple_wallet_key" >}}wallet key{{< /glossary_term >}}. Includes the wallet key's user: `salto.nebula.user.v1.User` and the wallet key assigned: `salto.nebula.user.v1.WalletKey`, as well as the actor who assigned it. #### `com.saltosystems.nebula.event.v1.walletkeycanceled` Event representing the cancelation of a user's {{< glossary_term "apple_wallet_key" >}}wallet key{{< /glossary_term >}}. Includes the wallet key's user: `salto.nebula.user.v1.User` and the wallet key canceled: `salto.nebula.user.v1.WalletKey`, as well as the actor who canceled it. #### `com.saltosystems.nebula.event.v1.unitmovedin` Event representing the move in of a {{< glossary_term "unit" >}}unit{{< /glossary_term >}}. Includes the unit and the actor who moved them in. See the [documentation on units](https://support.saltosystems.com/homelok/user-guide/property-manager/units/create-unit/) for more information. #### `com.saltosystems.nebula.event.v1.unitmovedout` Event representing the move out of a {{< glossary_term "unit" >}}unit{{< /glossary_term >}}. Includes the unit and the actor who moved them out. See the [documentation on units](https://support.saltosystems.com/homelok/user-guide/property-manager/units/move-out/) for more information. #### `com.saltosystems.nebula.event.v1.unitcreated` Event representing the creation of a {{< glossary_term "unit" >}}unit{{< /glossary_term >}}. Includes the unit that was created and the actor who created it. See the [documentation on units](https://support.saltosystems.com/homelok/user-guide/property-manager/units/create-unit/) for more information. #### `com.saltosystems.nebula.event.v1.unitupdated` Event representing the update of a {{< glossary_term "unit" >}}unit{{< /glossary_term >}}. Includes the unit that was updated and the actor who updated it. See the [documentation on units](https://support.saltosystems.com/homelok/user-guide/property-manager/units/create-unit/) for more information. #### `com.saltosystems.nebula.event.v1.unitdeleted` Event representing the deletion of a {{< glossary_term "unit" >}}unit{{< /glossary_term >}}. Includes the unit that was deleted and the actor who deleted it. See the [documentation on units](https://support.saltosystems.com/homelok/user-guide/property-manager/units/move-out/) for more information. #### `com.saltosystems.nebula.event.v1.emergencykeycreated` Event representing the creation of an emergency key. Includes the emergency key that was created and the actor who created it. #### `com.saltosystems.nebula.event.v1.emergencykeyupdated` Event representing the update of an emergency key. Includes the emergency key that was updated and the actor who updated it. #### `com.saltosystems.nebula.event.v1.emergencykeydeleted` Event representing the deletion of an emergency key. Includes the emergency key that was deleted and the actor who deleted it. #### `com.saltosystems.nebula.event.v1.accessgranted` Event representing access being granted to a user. This event indicates that a user's key was successfully validated and access permissions were activated. This event is typically used in scenarios where the device manages multiple destinations and cannot determine the user's final action, or where it represents a general access grant rather than a specific door unlock. This differs from `accesspointunlocked` in that: - It can enable multiple relays/destinations simultaneously (for example: elevator buttons for authorized floors). - It represents the **granting** of access rights rather than the **physical unlocking** of a specific access point. Common use case: - Controllers (elevators, multi-door, garages): enabling floor buttons, granting access to multiple doors, or triggering a garage door. Includes the device that granted access (currently `salto.nebula.controller.v1.Controller`) and the user who was granted access: `salto.nebula.user.v1.User`. For user access grants, the event includes the credential type used. The following credential types are available: - `salto.nebula.emergencykey.v1.EmergencyKey` - `salto.nebula.user.v1.CardKey` - `salto.nebula.user.v1.AppKey` - `salto.nebula.user.v1.WalletKey` - `salto.nebula.user.v1.Passcode`