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.

Tutorials on how to create and manage permanent sessions using the JSON Admin API. A permanent session generates an API key (authToken) that doesn't expire. To enable permanent sessions, the "enablePermanentJsonApiSessions" property in services.json must be set to true and the server restarted. Creating a permanent session also involves including the "permanentSession" property set to true in the createSession action call. The document provides examples of request structures for creating and verifying permanent sessions, showing how to use describeSessions to confirm if a session is permanent by checking the "permanentSession" property in the response.

session & services APIsession tutorialsservices tutorialshow to create sessionhow to configure servicessessions and services tutorialsjsonActionjsonAction APIadmin apisession managementhow to manage sessionshow to manage servicesservice managementcreate sessionpermanent sessionpermanent session tutorial

Tutorial: Create a permanent session

Tutorial for creating 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.

{
  "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": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

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