listSessions

Return a list of active sessions

The "listSessions" action returns a list of active sessions that the logged-in account is authorized to see. The list can be filtered to include sessions from specific usernames.

 

Request examples

Minimal

{
  "action": "listSessions",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
  "requestId": "2",
  "api": "admin",
  "action": "listSessions",
  "params": {
    "usernameFilter": [
      "jim"
    ]
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string"
  },
  "apiVersion": "1.0",
  "debug": "max",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Success

{
    "result": {
        "sessions": [
            {
                "username": "ADMIN",
                "description": "optional user description of session for troubleshooting",
                "authToken": "replaceWithAuthTokenFromCreateSession"
            }
        ]
    },
    "requestId": "00000045",
    "errorCode": 0,
    "errorMessage": "",
    "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Failure

{
  "authToken": "invalidAuthtoken",
  "requestId": "2",
  "debugInfo": {
    "request": {
      "authToken": "invalidAuthtoken",
      "api": "admin",
      "action": "listSessions",
      "requestId": "2"
    }
  },
  "errorCode": 12031,
  "errorMessage": "'authToken' does not match any existing session. Use a valid 'authToken' or use 'createSession' to create a valid 'authToken'."
}
 
 

 

Request properties ("params")

Property Description Default Type Limits (inclusive)

usernameFilter

The "usernameFilter" property contains usernames that filter the returned list of sessions by the accounts associated with those usernames.

 Optional with default of [] array 1 to 64 bytes

Response properties ("result")

Property Description Type Limits (inclusive)

sessions

The "sessions" property is an array of session objects where each session object minimally describes a session.

 array of objects

“authToken”

“description”

"username"

sessions

.username

The "username" property specifies the account name of a user or application.

All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.

In JSON DB API and JSON Hub API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.

Unlike other property names, such as "databaseName", "username" is all lowercase.

A zero-length username is invalid.

Note See System specifications for requirements of this and all other system properties.

In Key-Value actions, the "username" property is used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.

 

 

string

 

 

 1 to 64 bytes

sessions

.description

The "description" property provides additional information about an object, such as a label or thing. You can use it as internal or external documentation of a label's meaning, purpose, and usage.

Markdown is a good language for formatting description text. You must ensure the text is compatible with a JSON string. For example, you must escape a double quote character using the backslash character:  \".

 

In the Thing API, It defaults to "unknown" and is a string from 1 to 512 bytes. You cannot use it for lookups and filtering.

 

 string 1 to 65,500 bytes

sessions

.authtoken

The "authToken" property signifies that the client is authenticated and authorized.

It is supplied by the server in response to the connect action.

Clients must include it in all subsequent requests to validate that they are authenticated and authorized. If the client does not supply the correct values, the server returns an unauthorized error.

 string 0 to 255 bytes

Was this article helpful?

Give feedback about this article

Related Articles