The sessions API provides methods for creating and managing sessions. A session is synonymous with a user login into the signature chain. The full supported endpoint of the sessions URI is as follows:
sessions/verb/noun
The minimum required components of the URI are:
sessions/verb/noun
The following verbs are currently supported by this API command-set:
create - Generate a new session type specified by the noun.
unlock - Unlock the session to carry out specified operations.
list - List the active sessions on the particular node.
lock - Lock the session to stop a specified operations.
save - Save a specified session to the local database.
load - Load a specified session from the local database.
terminate - Terminates a session specified by the noun.
status - Returns status information for the session specified by the noun.
validate - Lock the session to stop a specified operations.
The following nouns are supported for this API command-set:
local - The location of the session.
Create a new session specified by given noun.
sessions/create/noun
This command only supports the local noun.
username : Required to identify the profile to create the session for.
password : Required to authenticate the password for creating the session.
pin : Required to authenticate the PIN for creating the session.
{
"genesis": "b7fa11647c02a3a65a72970d8e703d8804eb127c7e7c41d565c3514a4d3fdf13",
"session": "0aad63e028dd9e0f31f0b566831fea9dfc7db68fc2ba482a8ce975656971a67e"
}
[Completed in 1659.509829 ms]
genesis : This is the profile username hash, also known as owner hash.
session : When using multi-user API mode, an additional session value is returned and must be supplied in subsequent API calls, to allow the managing of multiple login sessions.
This will unlock the session specified by given noun and cache the PIN in encrypted memory to be used for all subsequent API calls for the specified operations.
sessions/unlock/noun
These commands only supports the local noun.
pin : Required to authenticate. The PIN for this profile.
session : Required by argument -multiuser=1 to be supplied to identify the user session. For single-user API mode the session should not be supplied.
mining : Required for unlocking mining transactions. This boolean value unlocks the session for mining.
notifications : Required for unlocking notifications. This boolean value unlocks the session to automatically process incoming notifications.
staking : Required for unlocking staking transactions. This boolean value unlocks the session for staking.
transactions : Required for unlocking transactions. This boolean value unlocks the session to allow creating or claiming transactions.
all : Use the all option to enable the mining, notifications, staking and mining options with a single parameter.
{
"unlocked": {
"mining": false,
"notifications": true,
"staking": true,
"transactions": false
}
}
[Completed in 1664.238652 ms]
unlocked : This will contain child elements describing which functions the session is currently unlocked for
mining : Boolean flag indicating whether the users sig chain is unlocked for mining.
notifications : Boolean flag indicating whether the users sig chain is unlocked for processing notifications.
staking : Boolean flag indicating whether the users sig chain is unlocked for staking.
transactions : Boolean flag indicating whether the users sig chain is unlocked for creating any transactions (except those automatically created through mining/processing notifications if those are unlocked).
This will list the active session details.
sessions/list/noun
These commands only supports the local noun.
session : Required by argument -multiuser=1 to be supplied to identify the user session. For single-user API mode the session should not be supplied.
{
}
This will lock the specified session by purging the PIN stored in encrypted memory, making it unavailable for use unless it is either unlocked or the PIN is passed in to all API requests.
sessions/lock/noun
These commands only supports the local noun.
pin : Required to authenticate. The PIN for this profile.
session : Required by argument -multiuser=1 to be supplied to identify the user session. For single-user API mode the session should not be supplied.
mining : Required for locking mining transactions. This boolean value locks the session for mining.
notifications : Required for locking notifications. This boolean value locks the session from processing incoming notifications.
staking : Required for locking staking transactions. This boolean value locks the session for staking.
transactions : Required for locking transactions. This boolean value locks the session for creating or claiming transactions.
all : Use the all option to disable the mining, notifications, staking and mining options with a single parameter.
{
"unlocked": {
"mining": false,
"notifications": true,
"staking": true,
"transactions": false
}
}
[Completed in 1664.238652 ms]
unlocked : This will contain child elements describing which functions the session is currently unlocked for
mining : Boolean flag indicating whether the users sig chain is unlocked for mining.
notifications : Boolean flag indicating whether the users sig chain is unlocked for processing notifications.
staking : Boolean flag indicating whether the users sig chain is unlocked for staking.
transactions : Boolean flag indicating whether the users sig chain is unlocked for creating any transactions (except those automatically created through mining/processing notifications if those are unlocked).
This will save the users session to the local database, allowing the session to be resumed at a later time without the need to login or unlock. The users PIN is required as this is used (in conjunction with the genesis) to encrypt the session data before persisting it to the local database.
sessions/save/noun
These commands only supports the local noun.
NOTE:
pin : Required to authenticate. The PIN for this profile.
session : Required by argument -multiuser=1 to be supplied to identify the user session. For single-user API mode the session should not be supplied.
{
"genesis": "b7fa11647c02a3a65a72970d8e703d8804eb127c7e7c41d565c3514a4d3fdf13",
"success": true
}
[Completed in 2.962459 ms]
genesis : This is the profile username hash, also known as owner hash.
success : Boolean flag indicating that the session was saved successfully .
This will resume a saved session from the local database, allowing a saved session to be resumed without the need to login or unlock. The profile username or genesis and PIN is required to decrypt and resume the saved session.
sessions/load/noun
These commands only supports the local noun.
NOTE:
pin : Required if authenticate. The PIN for this profile.
username: Required to identify the profile to load the session for. This is optional if the genesis is provided.
genesis : Required to identify the profile to load the session for. This is optional if the username is provided.
{
"genesis": "b7fa11647c02a3a65a72970d8e703d8804eb127c7e7c41d565c3514a4d3fdf13",
"session": "2ef9de11b19af82984ddf93275e7ba22c11fe9659d0667f79311c46732bbb7a4"
}
[Completed in 0.072625 ms]
genesis : This is the profile username hash, also known as owner hash.
session : When using multi-user API mode, an additional session value is returned to identify the session.
This will terminate an active session specified by given noun.
sessions/terminate/noun
This command only supports the local noun.
Note: This does not delete a saved session
pin : Required to authenticate. The PIN for this profile.
session : Required by argument -multiuser=1 to be supplied to identify the user session. For single-user API mode the session should not be supplied.
{
"success": true
}
[Completed in 1656.089478 ms]
success : Boolean flag indicating that the active session was terminated successfully.
Retrieve the session status specified by given noun.
sessions/status/noun
This command only supports the local noun.
session : Required by argument -multiuser=1 to be supplied to identify the user session. For single-user API mode the session should not be supplied.
{
"genesis": "b1cc162a96b1b5869f439101c0b135d9219799a64d1db340ae80435e4fc12207",
"accessed": 1678093730,
"duration": 36,
"location": "local",
"indexing": false,
"unlocked": {
"mining": false,
"notifications": false,
"staking": false,
"transactions": false
},
"saved": false
}
genesis : This is the profile username hash, also known as owner hash.
accessed : The unix timestamp at which the profile was last accessed.
location : The location of session.
unlocked : This will contain child elements describing which functions the session is currently unlocked for.
mining : Boolean flag indicating whether the users sig chain is unlocked for mining.
notifications : Boolean flag indicating whether the users profile is unlocked for processing notifications.
staking : Boolean flag indicating whether the profile is unlocked for staking.
transactions : Boolean flag indicating whether the profile is unlocked for creating any transactions (except those automatically created through mining/processing notifications if those are unlocked).