UserSessionService

The UserSessionService provides an API for fetching and managing a user's login sessions across different devices and applications. This service is essential for building features that allow users to view their active login locations, see which devices have accessed their account, and manage those sessions.

For a practical guide on using this service, please refer to the Managing User Sessions guide.

Methods#

getMyLoginSessions()#

Retrieves a paginated list of the current user's own login sessions.

Parameters

options
object
An object containing configuration options.
1 subfields
params
UserSessionQuery
default:{ page: 1, pageSize: 10 }
An object for pagination and filtering.
3 subfields

Returns

Promise<UserSessionList>
Promise
A promise that resolves to an object containing a list of sessions and pagination details.

Example

Fetching My Online Sessions

import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function fetchMySessions() {
  try {
    const sessionData = await sdk.userSession.getMyLoginSessions(
      {},
      { page: 1, pageSize: 5, status: 'online' }
    );
    console.log('Online Sessions:', sessionData.list);
    console.log('Total online sessions:', sessionData.paging.total);
  } catch (error) {
    console.error('Failed to fetch sessions:', error);
  }
}

fetchMySessions();

Example Response

{
  "list": [
    {
      "id": "z8V...",
      "appName": "My Blocklet",
      "appPid": "my-blocklet-pid",
      "lastLoginIp": "192.168.1.1",
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "updatedAt": "2023-10-27T10:00:00.000Z",
      "status": "online",
      "userDid": "zNK..."
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5,
    "total": 1
  }
}

getUserSessions()#

Retrieves all login sessions for a specific user DID. This method is typically used in administrative contexts.

Parameters

options
object
required
An object containing the user's DID and optional app URL.
2 subfields

Returns

Promise<UserSession[]>
Promise
A promise that resolves to an array of UserSession objects.

Example

Fetching Sessions for a Specific User

import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function fetchUserSessions(userDid) {
  try {
    const sessions = await sdk.userSession.getUserSessions({ did: userDid });
    console.log(`Sessions for user ${userDid}:`, sessions);
  } catch (error) {
    console.error('Failed to fetch user sessions:', error);
  }
}

fetchUserSessions('zNK...userDid...'); // Replace with a valid user DID

Example Response

[
  {
    "id": "z8V...",
    "appName": "My Blocklet",
    "appPid": "my-blocklet-pid",
    "lastLoginIp": "192.168.1.1",
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
    "updatedAt": "2023-10-27T10:00:00.000Z",
    "status": "online",
    "userDid": "zNK..."
  }
]

loginByUserSession()#

Initiates a new login based on an existing user session ID. This can be used for features like seamless sign-in across related applications.

Parameters

options
object
required
An object containing the session details required for login.
5 subfields

Returns

Promise<UserSession[]>
Promise
A promise that resolves to an array containing the new user session.

Example

Logging In with an Existing Session

import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();

async function loginWithSession(sessionDetails) {
  try {
    const newSessions = await sdk.userSession.loginByUserSession(sessionDetails);
    console.log('Successfully logged in with new session:', newSessions[0]);
  } catch (error) {
    console.error('Login by session failed:', error);
  }
}

const existingSession = {
  id: 'session_id_to_use',
  appPid: 'target_app_pid',
  userDid: 'zNK...userDid...',
  passportId: 'passport_id_string'
};

loginWithSession(existingSession);

Data Structures#

The following are the primary data structures used by the UserSessionService.

UserSession#

Represents a single login session for a user in a specific application.

id
string
required
Unique identifier for the session.
appName
string
required
The name of the application where the session originated.
appPid
string
required
The PID of the application.
lastLoginIp
string
required
The last known IP address for this session.
ua
string
required
The User-Agent string of the client device.
createdAt
string
The timestamp when the session was created.
updatedAt
string
required
The timestamp of the last activity for this session.
status
'online' | 'expired' | 'offline'
The current status of the session.
user
UserSessionUser
Detailed information about the user.
userDid
string
required
The DID of the user who owns the session.
visitorId
string
required
An identifier for the visitor/device.
passportId
string | null
required
The ID of the user's passport.
extra
object
required
Additional metadata.
1 subfields

UserSessionUser#

Contains detailed information about the user associated with a session.

did
string
required
The user's Decentralized Identifier (DID).
fullName
string
required
The full name of the user.
email
string
required
The user's email address.
avatar
string
required
URL to the user's avatar image.
pk
string
required
The user's public key.
role
string
required
The user's role within the application (e.g., 'owner', 'admin').
roleTitle
string
required
The display title for the user's role.
sourceProvider
'wallet' | 'auth0' | 'nft'
required
The provider used for authentication.
sourceAppPid
string | null
required
The PID of the application that sourced the user data.
remark
string
Any remarks or notes about the user.

UserSessionList#

A paginated list of user sessions.

list
UserSession[]
required
An array of user session objects.
paging
object
required
An object containing pagination details.
3 subfields

UserSessionQuery#

An object used to filter and paginate session queries.

page
number
required
The page number to retrieve.
pageSize
number
required
The number of sessions per page.
status
'online' | 'expired' | 'offline'
Filter sessions by their status.
TokenService
Types