Session and services Tutorials

JSON ADMIN API tutorials for using sessions and services

A permanent session creates an API key, which is a permanent "authToken" that never expires and permanently authorizes an account.

Create a permanent session.

This tutorial creates a permanent session by setting the "enablePermanentJsonApiSessions" to true in the services.json file and Including the "permanentSession" property, set to true, in the createSession action call.

The "enablePermanentJsonApiSessions" property is in the "jsonActionApiDefaults" section of services.json. To use persistent sessions, this property must be set to true. When it is changed, the server must be restarted. That section of the services.json file will look similar to this:

"jsonActionApiDefaults"
{
  "defaultApi": "hub",
  "defaultBinaryFormat": "hex",
  "defaultDatabaseName": "faircom",
  "defaultDebug": "max",
  "defaultOwnerName": "admin",
  "defaultResponseOptions":
  {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "idleConnectionTimeoutSeconds": 3600,
  "idleCursorTimeoutSeconds": 600,
  "defaultRetentionPolicy": "autoPurge",
  "defaultRetentionUnit": "week",
  "defaultRetentionPeriod": 4,
  "maxJsonApiSessions": 1024,
  "maxJsonApiSessionsPerIpAddress": 50,
  "maxJsonApiSessionsPerUsername": 50,
  "enablePermanentJsonApiSessions": true
},

Create a permanent session

Use the following example request to create a permanent session.

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

The response from that request will include an authToken that works like an API Key and authenticates an application without the need for a username/password or client certificate.

Confirm a session is permanent

Confirm that a session is permanent by calling describeSessions. In this example, we pass the authToken of the session we want to check.

{
  "api": "admin",
  "action": "describeSessions",
  "params": {
    "authTokens": [
      "replaceWithTheAuthTokensYouWantToCheck"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

You can omit the array for the "authTokens" property and describeSessions will report every session that is active on the server.

To see if a session is permanent, check the "permanentSession" property in the response.

{
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "result": {
    "sessions": [
      {
        "authToken": "authTokenThatWasChecked",
        "username": "ADMIN",
        "defaultDatabaseName": "faircom",
        "defaultOwnerName": "admin",
        "defaultBinaryFormat": "hex",
        "defaultResponseOptions": {
          "binaryFormat": "hex",
          "dataFormat": "objects",
          "numberFormat": "number"
        },
        "idleConnectionTimeoutSeconds": -1,
        "idleCursorTimeoutSeconds": 600,
        "defaultApi": "hub",
        "defaultDebug": "max",
        "transformBufferInitialBytes": 0,
        "permanentSession": true,
        "sessionStartTimestamp": "2024-10-09T05:01:23",
        "sessionLastAccessedTimestamp": "2024-10-09T05:01:23",
        "defaultRetentionPolicy": "autoPurge",
        "defaultRetentionUnit": "week",
        "defaultRetentionPeriod": 4,
        "hostname": "AdamH-LT-2021",
        "hostUuid": "d1430a57-5c8e-44db-adf6-2dbb17ae3e06",
        "hostIpAddresses": [
          "fe80::6fa:a534:ad1e:1643",
          "10.0.0.5"
        ],
        "hostServerNamePort": "FAIRCOMS",
        "hostSQLPort": 6597
      }
    ]
  },
  "errorCode": 0,  "errorMessage": ""
}

Since "permanentSession" is set to true, we know that the session associated with the authToken we checked is a permanent session.

Create a permanent session

API KeycreateSessionpermanent sessioncreate permanent session