← Events API

API for retrieving events from the event table

GET/v2/eventsGet events

Get events with optional filters. Permission is resolved in the following order (first match wins):

Super-user access: when an `organizationId` filter is provided and the caller is a super-user for that organization, access is granted. The `accountId`, `userId`, and `deviceId` filters are still validated against the organization.

Own-account filter: when the `accountId` filter matches the caller's own account, access is granted. The `organizationId`, `userId`, and `deviceId` filters are validated against the caller's admin-device set.

Fallback: all filters are validated against the caller's permissions. If no `deviceId` filter is supplied the results are automatically scoped to the caller's admin devices. Returns `403 Forbidden` if any filter references a resource the caller cannot access.

parameteraccountIdFilter by account ID (triggeredBy): Number
parameterorganizationIdFilter by organization ID: Number
parameteruserIdFilter by user ID (multiple space-separated values possible): Number
parameterdeviceIdFilter by device ID (multiple space-separated values possible): Number
parameterfromFilter events from this timestamp, inclusive (ISO 8601): String
parametertoFilter events up to this timestamp, exclusive (ISO 8601): String
parameteruntilFilter events until this timestamp, inclusive (ISO 8601): String
parametertypeFilter by event type (multiple space-separated values possible): "DeviceActivation" / "DeviceDeactivation" / "DeviceBoot" / "DeviceStatus" / "DeviceDebug" / "DeviceTamperVibration" / "DeviceTamperRotations" / "DeviceTamperFaultyPin" / "DeviceLocked" / "MatterCommissioning" / "ThreadConnection" / "AccountDeletion" / "AccountMutation" / "UserMutation" / "UserGroupMutation" / "DeviceGroupMutation" / "OrganizationMutation" / "DeviceMutation" / "ShareMutation" / "WebKeyMutation" / "CredentialMutation" / "RecalculateOrganization" / "DeviceDeleteEDPs" / "UserInviteAccepted" / "UserImpersonated" / "AccountAssigned" / "Login" / "AdvanceStreamTime"
parametercategoryFilter by event category (multiple space-separated values possible): "AccessEvent" / "DeviceEvent" / "AuditEvent" / "SystemEvent"
parametertriggeredByFilter by triggeredBy user ID (multiple space-separated values possible): Number
parameteruserGroupIdFilter by user group ID (multiple space-separated values possible): Number
parameterdeviceGroupIdFilter by device group ID (multiple space-separated values possible): Number
parameteroffsetPage offset (default: 0): Number
parametersizeNumber of items on Page (default: 50, max: 100): Number
headerAuthorizationAuthentication token (bearer token or API key).

Response

status200All ok, returned found events
status401Invalid authentication token
status403Insufficient rights
[{
"id" : Number,
"batchId" : String, UUID 4 formatted (e.g. "a426e157-8a5c-456a-8865-bec6394867ab"),
"triggeredBy" : {
"userId" : Number,
"accountId" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String,
"userExternalId" : String
},
"organization" : {
"id" : Number,
"name" : String
},
"category" : "AccessEvent" / "DeviceEvent" / "AuditEvent" / "SystemEvent",
"time" : Date/time UTC instant (ISO 8601, e.g. "2022-06-23T15:53:00.000Z"),
"type" : "DeviceActivation" / "DeviceDeactivation" / "DeviceBoot" / "DeviceStatus" / "DeviceDebug" / "DeviceTamperVibration" / "DeviceTamperRotations" / "DeviceTamperFaultyPin" / "DeviceLocked" / "MatterCommissioning" / "ThreadConnection" / "AccountDeletion" / "AccountMutation" / "UserMutation" / "UserGroupMutation" / "DeviceGroupMutation" / "OrganizationMutation" / "DeviceMutation" / "ShareMutation" / "WebKeyMutation" / "CredentialMutation" / "RecalculateOrganization" / "DeviceDeleteEDPs" / "UserInviteAccepted" / "UserImpersonated" / "AccountAssigned" / "Login" / "AdvanceStreamTime",
...
} and (depending on type) {
...
"type" : "AccountAssigned",
"category" : "SystemEvent",
"user" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String,
"externalId" : String
},
"account" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String
},
} or {
...
"type" : "AccountDeletion",
"category" : "SystemEvent",
"accountId" : Number,
"preliminary" : Boolean,
} or {
...
"type" : "AccountMutation",
"category" : "AuditEvent",
"account" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String
},
"mutation" : "Create" / "Update" / "Delete" / "AddItem" / "RemoveItem" / "UpdateItem" / "Install" / "Uninstall" / "Decommission" / "Transfer",
"lastName" : com.sesamsolutions.platform.common.TriOpt[String],
"firstName" : com.sesamsolutions.platform.common.TriOpt[String],
"emailAddress" : com.sesamsolutions.platform.common.TriOpt[com.sesamsolutions.platform.common.EmailAddress],
"phoneNumber" : com.sesamsolutions.platform.common.TriOpt[com.sesamsolutions.platform.common.PhoneNumber],
"registered" : Boolean,
} or {
...
"type" : "AdvanceStreamTime",
"category" : "SystemEvent",
} or {
...
"type" : "CredentialMutation",
"category" : "AuditEvent",
"credential" : {
"id" : Number,
"account" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String
},
"type" : "Google" / "Apple" / "Azure" / "Password",
"emailAddress" : String
},
"mutation" : "Create" / "Update" / "Delete" / "AddItem" / "RemoveItem" / "UpdateItem" / "Install" / "Uninstall" / "Decommission" / "Transfer",
"emailAddress" : String,
"emailMatched" : String,
} or {
...
"type" : "DeviceActivation",
"category" : "AccessEvent",
"device" : {
"id" : Number,
"name" : String
},
"account" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String
},
"user" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String,
"externalId" : String
},
"clicker" : {
"id" : Number,
"name" : String
},
"connect" : {
"id" : Number,
"name" : String
},
"clientInstanceId" : Number,
"clientId" : String,
"method" : "Pin" / "Button" / "Ble" / "Mqtt" / "Matter",
"pinIndex" : Number,
"pinName" : String,
"autoActivation" : Boolean,
"remoteActivation" : Boolean,
"webKeyActivation" : Boolean,
"keepActiveUntil" : Date/time UTC instant (ISO 8601, e.g. "2022-06-23T15:53:00.000Z"),
"activationTime" : scala.concurrent.duration.FiniteDuration,
"result" : "Success" / "CommandInvalid" / "ClientBlocked" / "HandshakeExpired" / "PermissionHashInvalid" / "PinInvalid" / "ButtonDisabled",
} or {
...
"type" : "DeviceBoot",
"category" : "DeviceEvent",
"device" : {
"id" : Number,
"name" : String
},
"bootReason" : "PowerOn" / "ResetPin" / "WatchdogReset" / "SoftReset" / "CpuLockUp",
"applicationVersion" : Number,
"bootloaderVersion" : Number,
"softDeviceVersion" : Number,
} or {
...
"type" : "DeviceDeactivation",
"category" : "AccessEvent",
"device" : {
"id" : Number,
"name" : String
},
"account" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String
},
"user" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String,
"externalId" : String
},
"clicker" : {
"id" : Number,
"name" : String
},
"connect" : {
"id" : Number,
"name" : String
},
"clientInstanceId" : Number,
"clientType" : String,
"method" : "Button" / "Ble" / "KeepActiveExpired" / "Matter",
} or {
...
"type" : "DeviceDebug",
"category" : "DeviceEvent",
"device" : {
"id" : Number,
"name" : String
},
"debugType" : "DebugClutchEvent" / "DebugDoorStatus",
"body" : JSON object,
} or {
...
"type" : "DeviceDeleteEDPs",
"category" : "SystemEvent",
"device" : {
"id" : Number,
"name" : String
},
} or {
...
"type" : "DeviceGroupMutation",
"category" : "AuditEvent",
"deviceGroup" : {
"id" : Number,
"name" : String
},
"mutation" : "Create" / "Update" / "Delete" / "AddItem" / "RemoveItem" / "UpdateItem" / "Install" / "Uninstall" / "Decommission" / "Transfer",
"name" : String,
"item" : {
"device" : {
"id" : Number,
"name" : String
}
},
} or {
...
"type" : "DeviceLocked",
"category" : "AccessEvent",
"device" : {
"id" : Number,
"name" : String
},
"status" : "Locked" / "Unlocked" / "Unknown",
"innerKnobRotation" : Number,
"innerKnobAngle" : Number,
} or {
...
"type" : "DeviceMutation",
"category" : "AuditEvent",
"device" : {
"id" : Number,
"name" : String
},
"mutation" : "Create" / "Update" / "Delete" / "AddItem" / "RemoveItem" / "UpdateItem" / "Install" / "Uninstall" / "Decommission" / "Transfer",
"name" : String,
} or {
...
"type" : "DeviceStatus",
"category" : "DeviceEvent",
"device" : {
"id" : Number,
"name" : String
},
"uptime" : Number,
"averageTemperature" : Number,
"voltageIdle" : Number,
"voltageUnderLoad" : Number,
"cumulativeActivationsBle" : Number,
"cumulativeActivationsPin" : Number,
"cumulativeActivationsButton" : Number,
"cumulativeActivationsMqtt" : Number,
"cumulativeClickerScans" : Number,
"wifiSignalStrength" : Number,
} or {
...
"type" : "DeviceTamperFaultyPin",
"category" : "AccessEvent",
"device" : {
"id" : Number,
"name" : String
},
"faultyEntries" : Number,
"duration" : Number,
} or {
...
"type" : "DeviceTamperRotations",
"category" : "AccessEvent",
"device" : {
"id" : Number,
"name" : String
},
"rotations" : Number,
} or {
...
"type" : "DeviceTamperVibration",
"category" : "AccessEvent",
"device" : {
"id" : Number,
"name" : String
},
"duration" : Number,
"axialAcceleration" : {
"average" : Number,
"min" : Number,
"max" : Number,
"variation" : Number
},
} or {
...
"type" : "Login",
"category" : "AuditEvent",
"credential" : {
"id" : Number,
"account" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String
},
"type" : "Google" / "Apple" / "Azure" / "Password",
"emailAddress" : String
},
"emailMatched" : String,
"clientId" : String,
} or {
...
"type" : "MatterCommissioning",
"category" : "DeviceEvent",
"device" : {
"id" : Number,
"name" : String
},
"matterCommissioningStatus" : "Commissioned" / "Decommissioned",
"nodeId" : Number,
"fabricId" : Number,
} or {
...
"type" : "OrganizationMutation",
"category" : "AuditEvent",
"mutation" : "Create" / "Update" / "Delete" / "AddItem" / "RemoveItem" / "UpdateItem" / "Install" / "Uninstall" / "Decommission" / "Transfer",
"name" : String,
} or {
...
"type" : "RecalculateOrganization",
"category" : "SystemEvent",
} or {
...
"type" : "ShareMutation",
"category" : "AuditEvent",
"share" : {
"id" : Number,
"device" : {
"id" : Number,
"name" : String
},
"deviceGroup" : {
"id" : Number,
"name" : String
},
"user" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String,
"externalId" : String
},
"userGroup" : {
"id" : Number,
"name" : String
}
},
"mutation" : "Create" / "Update" / "Delete" / "AddItem" / "RemoveItem" / "UpdateItem" / "Install" / "Uninstall" / "Decommission" / "Transfer",
"startDate" : com.sesamsolutions.platform.common.TriOpt[java.time.LocalDate],
"startTime" : com.sesamsolutions.platform.common.TriOpt[java.time.LocalTime],
"endDate" : com.sesamsolutions.platform.common.TriOpt[java.time.LocalDate],
"endTime" : com.sesamsolutions.platform.common.TriOpt[java.time.LocalTime],
"schedule" : com.sesamsolutions.platform.common.TriOpt[List[com.sesamsolutions.platform.devicemgmt.model.ScheduleEntry]],
"remoteActivate" : Boolean,
"assignClicker" : Boolean,
"deviceAdmin" : Boolean,
} or {
...
"type" : "ThreadConnection",
"category" : "DeviceEvent",
"device" : {
"id" : Number,
"name" : String
},
"connectivityEvent" : "NoChange" / "Established" / "Lost",
} or {
...
"type" : "UserGroupMutation",
"category" : "AuditEvent",
"userGroup" : {
"id" : Number,
"name" : String
},
"mutation" : "Create" / "Update" / "Delete" / "AddItem" / "RemoveItem" / "UpdateItem" / "Install" / "Uninstall" / "Decommission" / "Transfer",
"name" : String,
"item" : {
"user" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String,
"externalId" : String
},
"groupAdmin" : Boolean
},
} or {
...
"type" : "UserImpersonated",
"category" : "AuditEvent",
"user" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String,
"externalId" : String
},
} or {
...
"type" : "UserInviteAccepted",
"category" : "AuditEvent",
"user" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String,
"externalId" : String
},
"emailMatched" : String,
} or {
...
"type" : "UserMutation",
"category" : "AuditEvent",
"user" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String,
"externalId" : String
},
"mutation" : "Create" / "Update" / "Delete" / "AddItem" / "RemoveItem" / "UpdateItem" / "Install" / "Uninstall" / "Decommission" / "Transfer",
"lastName" : com.sesamsolutions.platform.common.TriOpt[String],
"firstName" : com.sesamsolutions.platform.common.TriOpt[String],
"emailAddress" : com.sesamsolutions.platform.common.TriOpt[com.sesamsolutions.platform.common.EmailAddress],
"phoneNumber" : com.sesamsolutions.platform.common.TriOpt[com.sesamsolutions.platform.common.PhoneNumber],
"emailMatched" : com.sesamsolutions.platform.common.TriOpt[com.sesamsolutions.platform.common.EmailAddress],
"superUser" : Boolean,
} or {
...
"type" : "WebKeyMutation",
"category" : "AuditEvent",
"webKey" : {
"id" : Number,
"device" : {
"id" : Number,
"name" : String
},
"deviceGroup" : {
"id" : Number,
"name" : String
},
"user" : {
"id" : Number,
"lastName" : String,
"firstName" : String,
"emailAddress" : String,
"externalId" : String
},
"userGroup" : {
"id" : Number,
"name" : String
},
"token" : String, UUID 4 formatted (e.g. "a426e157-8a5c-456a-8865-bec6394867ab")
},
"mutation" : "Create" / "Update" / "Delete" / "AddItem" / "RemoveItem" / "UpdateItem" / "Install" / "Uninstall" / "Decommission" / "Transfer",
}]

Example: Get events as support account

GET/v2/events

headerAuthorizationBearer cb01b60a-7e5a-4eb6-b421-a085c3ce2c98

Response

status200
headerAccess-Control-Expose-Headersauthorization, content-type
headerAccess-Control-Allow-Headersauthorization, content-type
headerAccess-Control-Allow-MethodsGET, POST, DELETE, OPTIONS, PUT
headerAccess-Control-Allow-Origin*
headerStrict-Transport-Securitymax-age=31536000; includeSubDomains
headerX-Frame-OptionsSAMEORIGIN
headerX-Content-Type-Optionsnosniff
headerX-XSS-Protection1; mode=block
headerContent-Security-Policydefault-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'
headerReferrer-Policyno-referrer
headerFeature-Policyself
headerPermissions-policyinterest-cohort=()
[]

Example: Get events filtered by organizationId as support account

GET/v2/events

parameterorganizationId1
headerAuthorizationBearer cb01b60a-7e5a-4eb6-b421-a085c3ce2c98

Response

status200
headerAccess-Control-Expose-Headersauthorization, content-type
headerAccess-Control-Allow-Headersauthorization, content-type
headerAccess-Control-Allow-MethodsGET, POST, DELETE, OPTIONS, PUT
headerAccess-Control-Allow-Origin*
headerStrict-Transport-Securitymax-age=31536000; includeSubDomains
headerX-Frame-OptionsSAMEORIGIN
headerX-Content-Type-Optionsnosniff
headerX-XSS-Protection1; mode=block
headerContent-Security-Policydefault-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'
headerReferrer-Policyno-referrer
headerFeature-Policyself
headerPermissions-policyinterest-cohort=()
[]

Example: Get events as normal account with own organization

GET/v2/events

parameterorganizationId1
headerAuthorizationBearer c71f9831-cd82-4267-922b-3d3d8379ba25

Response

status200
headerAccess-Control-Expose-Headersauthorization, content-type
headerAccess-Control-Allow-Headersauthorization, content-type
headerAccess-Control-Allow-MethodsGET, POST, DELETE, OPTIONS, PUT
headerAccess-Control-Allow-Origin*
headerStrict-Transport-Securitymax-age=31536000; includeSubDomains
headerX-Frame-OptionsSAMEORIGIN
headerX-Content-Type-Optionsnosniff
headerX-XSS-Protection1; mode=block
headerContent-Security-Policydefault-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'
headerReferrer-Policyno-referrer
headerFeature-Policyself
headerPermissions-policyinterest-cohort=()
[]