session.history

The session.history command is used to access and view session history.

Requires Org-Admin rights.

Session history can be requested by specifying:

  • A definite time period using a start and end date
  • A time period defined by the "last period of time" style query (last "24h", etc.)
  • Specific orgId shows the session history for a specified organization
  • Using the "showAll" parameter with super-admin rights allows viewing session histories of all organizations

TR50 Request

Last period of time request


{
  "1": {
    "command": "session.history",
    "params": {
      "orgId": "540f438174e00c1427000022",
      "sort": "whoAmI",
      "last": "24h"
    }
  }
}

Definite time period request


{
  "1": {
    "command": "session.history",
    "params": {
      "showAll": true,
      "limit": 20,
      "start": "2021-03-04T00:00:00Z",
      "end": "2021-03-04T23:59:59Z"
    }
  }
}

Request Parameters

Name Type Required Description
start* String When doing a definite time period request this is the timestamp for the start of the specified time window.
end* String When doing a definite time period request this is the timestamp for the end of the specified time window.
last String When doing a last period of time request this specifies the last X amount of time in seconds (s), minutes (m), hours (h), or days (d).
offset Integer The starting list offset, used for pagination, defaults to 0 if not specified. The maximum offset you can set is 5000
limit Integer Limits the number of results returned. The maximum limit you can set is 5000.
orgId String The object id identifying the organization.
sort String Sort parameter. Choices are "startTime", "whoAmI", "hasSuperAdmin", "hasSuperOps", "hasOrgAdmin", and "orgKey".
showAll Boolean True/false value to indicate showing session histories for all organizations. Limited to super-admins.
(*) Out of courtesy, instead of throwing an error, the API will always apply the date ranges provided in the correct direction.

TR50 Response

If the command is sent successfully a success message and the session records found are returned. Otherwise, an error and error message will be returned.

The result array only contains non-empty fields. Some of the returned fields are specific to users or things or both.

{
  "1":{
      "success":true,
      "params":{
         "count":2,
         "result":[
            {
               "ref":"19f107dc206a088d7d4c58c01c72b6bf80561153c52f9f0aaef86e43598adf94",
               "serverId":"server1-us-open-rigsby",
               "orgId":"533ef300310046187700007f",
               "orgKey":"YorkOrg",
               "appName":"Amazon Echo",
               "thingKey":"alexa",
               "thingId":"5a8ae0bb1c5bd741065bd754",
               "thingDefId":"5a8ae0771c5bd741065bd612",
               "whoAmI":"alexa",
               "ipAddress":"177.71.124.164",
               "hasSuperAdmin":false,
               "hasSuperOps":false,
               "hasOrgAdmin":true,
               "connInfo":{
                  "protocol":"MQTT",
                  "remoteAddr":"177.71.120.164:54664"
               },
               "ttl":180,
               "locale":"",
               "allowSubOrgAccess":null,
               "startTime":"2021-08-10T07:54:24.38Z",
               "endTime":"2021-08-10T08:20:40.199Z",
               "allAgreementsSigned":false
            },
			{
               "ref":"0e7697e4********************************************************",
               "serverId":"server1-us-open-rigsby",
               "orgId":"533ef300310046187700007f",
               "orgKey":"SurreyOrg",
               "userId":"5914ac74fe2a13755f083e06",
               "userName":"john.doe@telit.com",
               "whoAmI":"john.doe@telit.com",
               "ipAddress":"174.27.155.133",
               "hasSuperAdmin":true,
               "hasSuperOps":false,
               "hasOrgAdmin":false,
               "connInfo":{
                  "protocol":"HTTP",
                  "remoteAddr":"174.27.155.133"
               },
               "ttl":86400,
               "locale":"",
               "allowSubOrgAccess":null,
               "startTime":"2021-08-10T14:16:10.976Z",
               "orgSwitches":[
                  {
                     "orgId":"5cf885f41c5bd771c8065be8",
                     "orgKey":"SurreyOrg",
                     "ts":"2021-08-10T14:43:13.11Z"
                  },
                  {
                     "orgId":"533ef300310046187700007f",
                     "orgKey":"YorkOrg",
                     "ts":"2021-08-10T14:43:38.927Z"
                  },
                  {
                     "orgId":"5cf885f41c5bd771c8065be8",
                     "orgKey":"SurreyOrg",
                     "ts":"2021-08-10T14:45:44.993Z"
                  }
               ],
               "commandCount":119,
               "lastAccessed":"2021-08-10T14:45:46.771Z",
               "allAgreementsSigned":false
            },
      ]
    }
  }
}

Response Parameters

Name Type Description
count Integer The total number of records matching the start-end/last date criteria.
result Array The array of session records.

Result Array Object

Name Type Description
ref String Ref is an identifier of session.
serverId String The server on which the session resides.
orgId String The user or app token object id of the current organization.
orgKey String The key for the organization.
appName String The name of the application.
appToken String The application token used during authentication.
thingKey String The thing key used during authentication.
thingId String The object id of the thing.
thingDefId String The object id of the thing's thing definition.
userId String The object id of the user.
userName String The username of the user.
whoAmI String The thing key or user name associated with the session.
hasSuperAdmin Boolean Whether the thing or user has super-admin permission.
hasSuperOps Boolean Whether the thing or user is super-ops.
hasOrgAdmin Boolean Whether the thing or user is an organization admin.
connInfo Struct A struct containing the connection protocol and remote address.
ttl Integer Time to live (used by redis).
startTime String Starting time of the session.
commandCount Integer Number of commands carried out related to the session.
failureReason String The description of the authentication failure.