Skip to main content

"describeSessions"

JSON ADMIN "describeSessions" action returns a list of session objects

The "describeSessions" describes one or more sessions.

  • If the "authTokens" property is omitted, "describeSessions" describes all active sessions created by the account.

  • If the "authTokens" property is included, "describeSessions" describes only the sessions listed in the "authTokens" property and only those sessions that the account is authorized to view.

Request examples

Minimal request

{
  "api": "admin",
  "authToken": "anAuthorizationTokenFromTheServer",
  "action": "describeSessions"
}

Typical request

{
  "api": "admin",
  "requestId": "2",
  "authToken": "replaceWithValidAuthtoken",
  "action": "describeSessions",
  "params": {
    "authTokens": [
      "replaceWithValidAuthtoken",
      "replaceWithAnotherValidAuthtoken"
    ]
  }
}

Maximal request

{
  "requestId": "3",
  "authToken": "replaceWithValidAuthtoken",
  "api": "admin",
  "action": "describeSessions",
  "params": {
    "authTokens": [
      "replaceWithValidAuthtoken",
      "replaceWithAnotherValidAuthtoken"
    ]
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string"
  },
  "apiVersion": "1.0",
  "debug": "max"
}

Response examples

Successful response

{
    "authToken": "replaceWithValidAuthtoken",
    "result": {
        "sessions": [
            {
                "authToken": "replaceWithValidAuthtoken",
                "username": "ADMIN",
                "description": "",
                "defaultDatabaseName": "ctreeSQL",
                "defaultOwnerName": "admin",
                "defaultBinaryFormat": "base64",
                "defaultResponseOptions": {
                    "binaryFormat": "hex",
                    "dataFormat": "objects",
                    "numberFormat": "number"
                },
                "idleConnectionTimeoutSeconds": 3600,
                "idleCursorTimeoutSeconds": 600,
                "defaultApi": "db",
                "defaultDebug": "none",
                "sessionStartTimestamp": "2023-03-31T15:15:51",
                "sessionLastAccessedTimestamp": "2023-03-31T15:38:11",
                "hostname": "zeus2",
                "hostUuid": "204f0f2f-dfba-4765-9352-504b46980ce9",
                "hostIpAddresses": ["10.243.251.132"],
                "hostServerNamePort": "5597",
                "hostSQLPort": "6597"
            }
        ]
    },
    "requestId": "00000008",
    "errorCode": 0,
    "errorMessage": ""
}

Failure response

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

Use the describeSessions API action to return one or more session objects that the logged-in account is authorized to view

API actionsJSON ADMIN APIjsonActionadmin sessiondescribeSessiondescribeSessionsdescribesSessiondescribesSessionsdescribe session

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Properties summary

Table 1. "params" properties summary

Property

Description

Default

Type

Limits (inclusive)

authTokens

contains one or more authorization token strings

[]

array

At least one "authToken"



"result"

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

Essential information:

Properties summary

Table 2. "result" properties summary

Property

Description

Type

Limits (inclusive)

sessions

contains session objects where each session minimally describes a session

array of objects

session
.authtoken

signifies that the client is authenticated and authorized

string

0 to 225 bytes

session
.defaultBinaryFormat

specifies the default value for the "binaryFormat" property, which tells the server how to parse binary data from the client making it useful when the binary format is not specified in the action request

string

"base64"
"hex"
"utf8"
session
.defaultDatabaseName

specifies the default value of the "databaseName" property

string

1 to 64 bytes

session
.defaultResponseOptions

specifies a default value for "responseOptions" that is used by default in all other action calls

object

One of the following:

"numberFormat"
"dataFormat"
"binaryFormat"
session
.defaultOwnerName

specifies the initial value of the "defaultOwnerName" property used by JSON APIs and FairCom's web application

string

0 to 256 bytes

session
.description

describes an object for later identification

string

0 to 65,500 bytes

session
.hostname

specifies the name of the host device

string

session
.hostUuid

specifies the universal identifier of the server instance

string

session
.hostIpAddresses

specifies the IP addresses of the host

array of strings

session
.hostServerNamePort

specifies the server's ISAM port or server name

string

session
.hostSQLPort

contains the server's SQL port

string

session
.idleConnectionTimeoutSeconds

specifies the number of seconds that a session with no activity will stay open

integer

0 to 2147483647

session
.idleCursorTimeoutSeconds

specifies the number of seconds to keep a cursor open

integer

0 to 2147483647

session
.sessionStartTimestamp

specifies the UTC date and time (in ISO 8601 format) when the session was created

string

session
.sessionLastAccessedTimestamp

specifies the UTC date and time (in ISO 8601 format) when the session last received a JSON Action message, including the last time the session was pinged

string

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.