Skip to main content

"createSession" (admin API)

JSON ADMIN "createSession" action logs into the FairCom server

The "createSession" action logs into the server. "createSession" returns the "authToken", which is needed for all other actions (except for "pingSession").

Request examples

Minimal request

{
  "api": "admin",
  "action": "createSession",
  "params": {
    "username": "CHANGE",
    "password": "CHANGE"
  }
}

Maximal request

{
  "requestId": "2",
  "api": "admin",
  "action": "createSession",
  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex",
    "defaultResponseOptions": {
      "dataFormat": "objects",
      "numberFormat": "string",
      "binaryFormat": "hex"
    },
    "idleConnectionTimeoutSeconds": 60000,
    "permanentSession": "true",
    "idleCursorTimeoutSeconds": 60000
  },
  "responseOptions": {
    "dataFormat": "objects",
    "numberFormat": "string",
    "binaryFormat": "hex"
  },
  "apiVersion": "1.0",
  "debug": "max"
}

Response examples

Successful response

{
  "result": {
    "username": "accountName",
    "description": "optional user-defined description of the session",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex",
    "defaultResponseOptions": {
      "dataFormat": "objects",
      "numberFormat": "string",
      "binaryFormat": "hex"
    },
    "idleConnectionTimeoutSeconds": 60000,
    "idleCursorTimeoutSeconds": 60000,
    "defaultApi": "db",
    "defaultDebug": "max",
    "sessionStartTimestamp": "2024-01-23T12:34:28",
    "sessionLastAccessedTimestamp": "2024-01-23T12:34:56",
    "authToken": "replaceWithAuthTokenFromCreateSession"
  },
  "requestId": "2",
  "errorCode": 0,
  "errorMessage": ""
}

Failure response

{
  "requestId": "2",
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "createSession",
      "params": {
        "username": "CHANGE",
        "password": "CHANGE",
        "description": "optional user description of session for troubleshooting",
        "defaultApi": "db",
        "defaultDebug": "max",
        "defaultDatabaseName": "ctreeSQL",
        "defaultOwnerName": "admin",
        "defaultBinaryFormat": "hex",
        "defaultResponseOptions": {
          "dataFormat": "objects",
          "numberFormat": "string",
          "binaryFormat": "hex"
        },
        "idleConnectionTimeoutSeconds": 60000,
        "idleCursorTimeoutSeconds": 60000
      },
      "apiVersion": "1.0",
      "requestId": "2",
      "responseOptions": {
        "dataFormat": "objects",
        "numberFormat": "string",
        "binaryFormat": "hex"
      },
      "debug": "max"
    }
  },
  "errorCode": 450,
  "errorMessage": "Unexpected exception during connection pool creation - Not able to validate the connection for user [CHANGE] to local port [FAIRCOMS]."
}

Use the createSession API action to log into the server

API actionsJSON ADMIN APIjsonActioncreateSessioncreateSessionscreatesSessioncreatesSessionscreate sessionAPI Key

"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)

defaultApi

(optional) specifies the default value of the "api" property when "api" is omitted from an action request

FairCom DB defaults to "db"
FairCom Edge defaults "hub"
FairCom MQ defaults "mq"

string

"admin"
"hub"
"mq"
"db"

defaultBinaryFormat

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

"hex"

string

One of the following: "base64", "hex", or "byteArray".

defaultDatabaseName

(optional) specifies the default value of the "databaseName" property

FairCom DB defaults to "ctreeSQL"
FairCom Edge defaults to "faircom"
FairCom MQ defaults to "faircom"

string

1 to 64 bytes

defaultDebug

(optional) specifies the default value of the "debug" property for all requests in a session

"max"

string

One of the following:

"none"
"max"

defaultOwnerName

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

"admin"

string

1 to 64 bytes

defaultResponseOptions

(optional) specifies a default value for "responseOptions" that is used by default in all other action calls. "includeFields" and "excludeFields" are mutually exclusive and "includePaths" and "excludePaths" are mutually exclusive

{}

object

"numberFormat"
"dataFormat"
"binaryFormat"
defaultResponseOptions
.binaryFormat

(optional) specifies how binary values are returned

"base64"

string

One of the following: "base64", "hex", or "byteArray".

defaultResponseOptions
.dataFormat

(optional) specifies what format the results will be returned in

"arrays"

string

"arrays"
"default"
"objects"
defaultResponseOptions
.numberFormat

(optional) specifies how numbers are formatted in the JSON response message

"number"

string

"number"
"string"

description

(optional) describes an object for later identification

""

string

0 to 65,500 bytes

idleConnectionTimeoutSeconds

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

3600

integer

0 to 2147483647

idleCursorTimeoutSeconds

(optional) specifies the number of seconds to keep a cursor open

600

integer

1 to 2147483647

password

authenticates an account

Required - No default value

string

0 to 256 bytes

permanentSession

(optional) persists a session. Its authToken never expires because the server permanently associates it with the session's username and settings

false

Boolean

true
false

username

specifies the account name of a user or application

Required - No default value

string

1 to 64 bytes



"binaryFormat"

"defaultBinaryFormat"

"defaultDebug"

"defaultDebug" is an optional string enum that defined the default value of the "debug" property for all requests in a session. It defaults to "max".

Important

This is different than the "debug" property in that the "debug" property can be universally used in any action while the "defaultDebug" property is only set in the "createSession" action and sets the "debug" property for any action run using the session being created.

Essential information

  • Possible values include:

    • "none"

    • "max"

  • If "defaultDebug" is omitted or set to null, it defaults to "max".

    This causes the server to include the "debugInfo" property in the response.

    This setting is typically used in development environments and for temporarily troubleshooting issues in production environments.

  • For maximum performance set set "defaultDebug" to "none" .

    This causes the server to omit the "debugInfo" property in the response.

    This setting is typically used in production and staging environments where it is desirable to have maximum performance and minimal network traffic.

"defaultResponseOptions"

The "defaultResponseOptions" property is a "responseOptions" object. It defines a default value for "responseOptions" that is used by default in all other action calls. It defaults to an empty object.

Essential information

  • JSON NAV allows you to choose how your program detects errors. By default, all error properties are included in each response – unless you override this behavior as shown in the example.

  • The example omits the error object in all responses and omitting the error object makes it easier for statically typed languages, such as C, C++, Java, C#, and VB, because they prefer properties to always be present. To help these languages, the "errorCode", "errorMessage", and "errorData" properties are always present whether there is an error or not.

Example

"defaultResponseOptions": {
      "dataFormat": "objects",
      "numberFormat": "string",
      "binaryFormat": "hex"
    }

"binaryFormat"

"dataFormat"

The "dataFormat" property is an optional, case-insensitive string enum that defines the format of the response in the "data" property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request and another occurs in a response. They all indicate how data is formatted.

  • "dataFormat" in the request inside "responseOptions" determines how the "data" property in the response is formatted.

    Possible values include:

    • "arrays"

      This is the default and causes the server to return results as an array of arrays, which is the most efficient.

    • "objects"

      This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

  • "dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.

    Possible values include:

    • "arrays"

      This causes the server to return results as an array of arrays, which is the most efficient.

    • "objects"

      This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

    • "autoDetect"

      This is the default and causes the server to automatically detect the format of the data in the "sourceData" property.

  • "dataFormat" in the response shows the client how the server formatted the "data" property.

    Possible values include:

    • "arrays"

      This is the default and causes the server to return results as an array of arrays, which is the most efficient.

    • "objects"

      This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

"idleConnectionTimeoutSeconds"

The "idleConnectionTimeoutSeconds" property is an optional integer from 0 to 2,147,483,647. It is the number of seconds that a session with no activity will stay open.

A value of 0 keeps a session open indefinitely.

"idleCursorTimeoutSeconds"

The "idleCursorTimeoutSeconds" property is an optional integer from 0 to 2,147,483,647. It is the number of seconds to keep a cursor open.

Essential information

  • Each time a cursor retrieves records, the cursor timer restarts.

  • A value of -1 keeps a cursor open indefinitely.

  • A value of 0 immediately closes a cursor after the current operation.

"password"

The "password" property is a required string from 0 to 256 bytes. "password" authenticates an account.

Essential information

  • The "password" property is required by the "createSession" action for authentication.

  • It is possible, but not recommended, for a password policy to allow a zero-length string.

"permanentSession"

The "permanentSession" property is an optional Boolean that indicates if a session is permanent. It defaults to false.

Important

Before you can create permanent sessions, you must add "enablePermanentJsonApiSessions": true to the "jsonActionApiDefaults" section of the <faircom>/config/services.json file.

If "permanentSession" is set to true when "createSession" is called, the server sets the authtoken as permanent. The authtoken is associated with the settings and authorizations of the user who created the session. It is always valid even after the server restarts. A permanent authToken works like an API Key and authenticates an application without the need for a username/password or a client certificate. Multiple applications can use the same permanent authToken.

Warning

A permanent "authToken" is potentially less secure than a temporary one.

  • A permanent "authToken" never becomes invalid, which makes it easier for an attacker to find it using brute force.

  • A permanent "authToken" is persisted by an application, which increases the opportunity for an attacker to find it.

  • A permanent "authToken" allows each application server to share the same session, which potentially allows an attacker to change session settings for all application servers.

Essential information

  • When you set the "permanentSession" property to true in "createSession" , it creates a permanent session and returns a permanent "authToken" .

  • Developers and applications can use a permanent authToken in JSON actions without needing to call createSession to get a temporary authToken.

  • You must protect a permanent "authToken" as you would a password or API key because it represents a permanently authenticated server session.

  • A permanent session does not expire. You can also prevent a temporary session from expiring by setting its "idleConnectionTimeoutSeconds" property to 0.

  • A permanent "authToken" uses the authorization and settings of the account that originally created the session. All actions performed in the session are performed using that account's authorizations, and account settings, such as its default database and owner.

  • You can use "alterSession" to modify the settings of a permanent session, but you cannot use it to turn a temporary session into a permanent session.

  • If multiple application servers use the same permanent "authToken", they share the same permanent session settings. Consider the following:

    • If one application server uses "alterSession" to change a permanent session's settings, the other application servers automatically use the new settings. To avoid confusion and errors, applications must specify all JSON action property values and not rely on session defaults.

    • You cannot use different sessions to determine which app server executes an action. This makes troubleshooting more difficult.

    • An application must create and use a transaction to protect the visibility and integrity of multiple operations from other applications. This is true for permanent and temporary sessions.

  • The FairCom server securely stores each permanent "authToken" in the encrypted faircom.fcs file.

"username"

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

Essential information

  • 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.

"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)

authToken

signifies that the client is authenticated and authorized

string

0 to 255 bytes

defaultBinaryFormat

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

string

One of the following: "base64", "hex", or "byteArray".

defaultDatabaseName

(optional) specifies the default value of the "databaseName" property

string

1 to 64 bytes

defaultOwnerName

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

string

1 to 64 bytes

defaultResponseOptions

(optional) specifies a default value for "responseOptions" that is used by default in all other action calls. "includeFields" and "excludeFields" are mutually exclusive and "includePaths" and "excludePaths" are mutually exclusive

object

One of the following:

"includeFields"
"excludeFields"
"includePaths"
"excludePaths"
"omit"
"numberFormat"
"dataFormat"
defaultResponseOptions
.binaryFormat

specifies how binary values are returned

string

One of the following: "base64", "hex", or "byteArray".

defaultResponseOptions
.dataFormat

specifies what format the results will be returned in

string

"arrays"
"default"
"objects"
defaultResponseOptions
.numberFormat

specifies how numbers are formatted in the JSON response message

string

"number"
"string"

description

(optional) describes an object for later identification

string

0 to 65,500 bytes

idleConnectionTimeoutSeconds

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

integer

0 to 2147483647

idleCursorTimeoutSeconds

(optional) specifies the number of seconds to keep a cursor open

integer

0 to 2147483647

username

specifies the account name of a user or application

string

1 to 64 bytes



"authToken"

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

Essential information

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

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

"binaryFormat"

"defaultBinaryFormat"

"defaultResponseOptions"

The "defaultResponseOptions" property is a "responseOptions" object. It defines a default value for "responseOptions" that is used by default in all other action calls. It defaults to an empty object.

Essential information

  • JSON NAV allows you to choose how your program detects errors. By default, all error properties are included in each response – unless you override this behavior as shown in the example.

  • The example omits the error object in all responses and omitting the error object makes it easier for statically typed languages, such as C, C++, Java, C#, and VB, because they prefer properties to always be present. To help these languages, the "errorCode", "errorMessage", and "errorData" properties are always present whether there is an error or not.

Example

"defaultResponseOptions": {
      "dataFormat": "objects",
      "numberFormat": "string",
      "binaryFormat": "hex"
    }

"binaryFormat"

"dataFormat"

The "dataFormat" property is an optional, case-insensitive string enum that defines the format of the response in the "data" property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request and another occurs in a response. They all indicate how data is formatted.

  • "dataFormat" in the request inside "responseOptions" determines how the "data" property in the response is formatted.

    Possible values include:

    • "arrays"

      This is the default and causes the server to return results as an array of arrays, which is the most efficient.

    • "objects"

      This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

  • "dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.

    Possible values include:

    • "arrays"

      This causes the server to return results as an array of arrays, which is the most efficient.

    • "objects"

      This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

    • "autoDetect"

      This is the default and causes the server to automatically detect the format of the data in the "sourceData" property.

  • "dataFormat" in the response shows the client how the server formatted the "data" property.

    Possible values include:

    • "arrays"

      This is the default and causes the server to return results as an array of arrays, which is the most efficient.

    • "objects"

      This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

"idleConnectionTimeoutSeconds"

The "idleConnectionTimeoutSeconds" property is an optional integer from 0 to 2,147,483,647. It is the number of seconds that a session with no activity will stay open.

A value of 0 keeps a session open indefinitely.

"idleCursorTimeoutSeconds"

The "idleCursorTimeoutSeconds" property is an optional integer from 0 to 2,147,483,647. It is the number of seconds to keep a cursor open.

Essential information

  • Each time a cursor retrieves records, the cursor timer restarts.

  • A value of -1 keeps a cursor open indefinitely.

  • A value of 0 immediately closes a cursor after the current operation.

"username"

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

Essential information

  • 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.

Would you like to provide feedback?