Sessions and Services Concepts

An application must create a session before it can run JSON actions. The only action you can run without a session is "pingSession".

A session begins when you execute the "createSession" action, which requires authentication using a username/password or a client certificate. The server performs all session actions under the authorization of the account that created the session.

If authentication is successful, the server allocates resources, establishes the session, and returns an "authToken" that the application must use in all subsequent JSON action requests. The authentication token uniquely identifies the session.

A session is stateful. The state includes the authorization token, description, maximum idle timeout, and default settings for JSON actions, such as API, database, and owner. You can also control the format of responses, including binary data, number format, and debug level.

Session state also includes cursors and transactions that you create. A session automatically creates a transaction for each database action and runs it against a shared connection pool for maximum speed and efficiency. If you manually create one or more multi-statement transactions, the session creates a dedicated database connection to run JSON actions containing those transactions.

By default, sessions are temporary and expire automatically when the connection has no activity for the number of seconds specified by the "idleConnectionTimeoutSeconds" property or when you run the "deleteSession" action. When a session terminates, the server releases its resources, including database connections, cursors, transactions, and RAM.

You can create permanent sessions that never expire. A permanent session is identified by a permanent "authToken" that works like an API key. You can run the "deleteSession" action to remove permanent sessions.

A permanent session creates an API key, which is a permanent "authToken" that never expires and permanently authorizes an account. This means that users can perform frequent operations without specifying time establishing a connection and authenticating an account. It's like having a private entrance to a library that doesn't require scanning a library card.

However, this can increase security risks. In the unlikely event that an unauthorized person gained access to the account linked to the permanent session, they would have full access to the database. Typically, permanent sessions should only be created using accounts with limited access and permissions in the database to reduce the likelihood of a bad actor gaining unfettered access to the database and holding it ransom.

Maintaining a permanent session to a server can also more quickly deplete resources for the client and server alike. If there are too many permanent sessions, they can eventually exhaust server resources, leading to reduced performance.

A service typically either collects data and stores it in an integration table or takes data in an integration table and delivers it to an external system. A server may have multiple services that each perform different tasks and functions on the data in the database. The service API enables administrators to start, stop, resume, restart, shut down, start-up, and otherwise manage the various services used by the server. In a library, the services API would be similar to a facility manager who can schedule and manage wok to be performed in the library by other companies, such as cleaning, indexing, or maintenance.