Managing User Sessions

The @blocklet/js-sdk provides a UserSessionService to help you fetch and manage user login sessions across different devices. This is particularly useful for building features like a "Security" or "Devices" page where users can see all their active sessions and understand where their account is being used.

This guide will walk you through the common use cases for managing user sessions.

Accessing the UserSessionService#

First, get an instance of the Blocklet SDK. The UserSessionService is available under the userSession property.

SDK Initialization

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

const sdk = getBlockletSDK();
const userSessionService = sdk.userSession;

Fetching Your Own Login Sessions#

The most common task is to retrieve the list of sessions for the currently authenticated user. The getMyLoginSessions method allows you to do this with support for pagination and filtering.

Fetching the current user's sessions

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

async function fetchMySessions() {
  try {
    const sdk = getBlockletSDK();
    // Fetch the first page of 10 online sessions
    const result = await sdk.userSession.getMyLoginSessions({}, {
      page: 1,
      pageSize: 10,
      status: 'online', // Optional filter: 'online' | 'expired' | 'offline'
    });

    console.log(`Total online sessions: ${result.paging.total}`);
    result.list.forEach(session => {
      console.log(`- Session on ${session.ua} last active at ${session.updatedAt}`);
    });
  } catch (error) {
    console.error('Failed to fetch sessions:', error);
  }
}

fetchMySessions();

Parameters#

The method signature is getMyLoginSessions({ appUrl?: string }, params: UserSessionQuery). The second argument is a query object with the following parameters:

page
number
default:1
The page number to retrieve.
pageSize
number
default:10
The number of sessions per page.
status
'online' | 'expired' | 'offline'
Filter sessions by their current status.

Response#

The method returns a promise that resolves to a UserSessionList object.

object
The response object containing the session list and pagination details.
2 subfields

Fetching Sessions for a Specific User#

In some cases, like an admin dashboard, you might need to fetch login sessions for a user other than the one who is currently logged in. The getUserSessions method allows you to do this by providing a user's DID.

Fetching sessions for a specific DID

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

async function fetchUserSessions(userDid) {
  try {
    const sdk = getBlockletSDK();
    const sessions = await sdk.userSession.getUserSessions({ did: userDid });

    console.log(`Found ${sessions.length} sessions for user ${userDid}:`);
    sessions.forEach(session => {
      console.log(`- Session ID: ${session.id}, App: ${session.appName}`);
    });
  } catch (error) {
    console.error(`Failed to fetch sessions for user ${userDid}:`, error);
  }
}

// Replace with the target user's DID
fetchUserSessions('zNK...some...user...did');

Parameters#

did
string
required
The DID of the user whose sessions to fetch.
appUrl
string
The base URL of the application. Defaults to the current Blocklet's service URL.

Response#

The method returns a promise that resolves to an array of UserSession objects.

UserSession[]
An array of user session objects for the specified user.
1 subfields


This guide has covered the primary ways to retrieve user session information using the SDK. For a complete list of all available methods and detailed type definitions, please refer to the UserSessionService API Reference.

Authentication
API Reference