Skip to main content

"listSessions" (JSON Action)

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.

Links: Concepts | Tutorials | FAQs

Request examples

Minimal

{
  "api": "admin",
  "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'."
}

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.

API actionsJSON ADMIN APIJSON Actionadmin sessionlistSessionlistSessionslistsSessionlistsSessionslist sessionreturn session informationcheck logged in sessionsfilter user sessionsactive sessionsview session informationaccess session information

"params"

The "params" property is an object that contains an action's request parameters as defined by a set of properties. Each action defines its own required and optional properties. See System limits for a comprehensive overview of property requirements and limitations.

Table 1. listSessions "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

usernameFilter

(optional) contains strings of usernames of accounts in order to filter a list of sessions.

[]

array

1 to 64 bytes



"usernameFilter"

The "usernameFilter" property is an optional array containing usernames that filter the returned list of sessions by the accounts associated with those usernames.

"result"

The "result" property is a required object set by the server that contains the result of an action.

Table 2. listSessions "result" property summaries

Property

Description

Type

Contents

sessions

contains session objects where each session minimally describes a session

array of objects

0 or more objects

session
.authtoken

signifies that the client is authenticated and authorized

string

0 to 225 bytes

session
.description

(optional) identifies the object by this description.

string

0 to 65,500 bytes

session
.username

specifies the account name of a user or application.

string

1 to 64 bytes



"sessions"

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

"authToken"

The "authToken" property signifies that the client is authenticated and authorized by the server. It is required except in "pingSession" and "createSession". For "pingSession" and "createSession" it defaults to an empty string.

The server generates a unique authentication token in response to "createSession". Clients must include it in all subsequent requests. If the client does not supply a valid "authToken", the server returns error 12031.

You can create a permanent "authToken" by setting the "permanentSession" property to true when you create a session. A permanent "authToken" works like an API key and does not expire.

"description"

The "description" property is an optional string that allows you to describe an object for later identification.

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },

"username"

The "username" property is a required string from 1 to 64 bytes. It is the account name of a user or application.

  • It is required by the "createSession" action for authentication.

  • 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 limits for requirements of this and all other system properties.