User & Access Management

This section provides a detailed reference for queries related to managing users, roles, permissions, sessions, and access keys within Blocklet Server. These queries allow you to retrieve information about your application's users and their access levels.
For operations that modify user and access data, such as creating users or updating permissions, please refer to the User & Access Management Mutations documentation.
User Queries#getUsers#Retrieves a paginated list of users, with options for filtering and sorting.
Parameters
input
RequestUsersInput
required
An object containing the query parameters.
5 subfields
Returns
ResponseUsers
An object containing the list of users and pagination information.
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchUsers() {
  try {
    const { users, paging } = await client.getUsers({
      input: {
        teamDid: 'z1...',
        paging: { page: 1, pageSize: 10 },
        query: {
          role: 'guest',
          approved: true,
          search: 'john.doe',
        },
        sort: {
          lastLoginAt: -1, // Sort by last login time descending
        },
      },
    });
    console.log('Fetched users:', users);
    console.log('Pagination info:', paging);
  } catch (error) {
    console.error('Error fetching users:', error);
  }
See all 3 lines
Example Response
{
  "code": "ok",
  "users": [
    {
      "did": "z8ia...",
      "pk": "...",
      "role": "guest",
      "avatar": "/path/to/avatar.png",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "approved": true,
      "createdAt": 1672531200,
      "lastLoginAt": 1675209600
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "pageCount": 1
  }
}
getUser#Retrieves the details of a single user by their DID.
Parameters
input
RequestTeamUserInput
required
An object containing the query parameters.
3 subfields
Returns
user
UserInfo
The requested user object.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchUser(userDid) {
  try {
    const { user } = await client.getUser({
      input: {
        teamDid: 'z1...',
        user: { did: userDid },
        options: {
          includePassports: true,
          includeTags: true,
        },
      },
    });
    console.log('User details:', user);
  } catch (error) {
    console.error('Error fetching user:', error);
  }
}

fetchUser('z8ia...'); // Replace with a valid user DID
Example Response
{
  "code": "ok",
  "user": {
    "did": "z8ia...",
    "fullName": "Jane Doe",
    "email": "jane.doe@example.com",
    "role": "admin",
    "approved": true,
    "passports": [],
    "tags": []
  }
}
getUsersCount#Retrieves the total count of users for a specific team or blocklet.
Parameters
input
TeamInput
required
An object containing the team DID.
1 subfields
Returns
count
number
The total number of users.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function countUsers() {
  try {
    const { count } = await client.getUsersCount({
      input: { teamDid: 'z1...' },
    });
    console.log('Total users:', count);
  } catch (error) {
    console.error('Error counting users:', error);
  }
}

countUsers();
Example Response
{
  "code": "ok",
  "count": 125
}
getUsersCountPerRole#Retrieves the count of users for each role within a team or blocklet.
Parameters
input
TeamInput
required
An object containing the team DID.
1 subfields
Returns
counts
KeyValue[]
An array of objects, where each object's `key` is the role name and `value` is the count.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function countUsersByRole() {
  try {
    const { counts } = await client.getUsersCountPerRole({
      input: { teamDid: 'z1...' },
    });
    console.log('User counts per role:', counts);
  } catch (error) {
    console.error('Error counting users by role:', error);
  }
}

countUsersByRole();
Example Response
{
  "code": "ok",
  "counts": [
    { "key": "owner", "value": 1 },
    { "key": "admin", "value": 5 },
    { "key": "member", "value": 119 }
  ]
}
getOwner#Retrieves the user information for the owner of a blocklet or team.
Parameters
input
TeamInput
required
An object containing the team DID.
1 subfields
Returns
user
UserInfo
The owner's user object.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchOwner() {
  try {
    const { user } = await client.getOwner({
      input: { teamDid: 'z1...' },
    });
    console.log('Owner info:', user);
  } catch (error) {
    console.error('Error fetching owner:', error);
  }
}

fetchOwner();
Example Response
{
  "code": "ok",
  "user": {
    "did": "zNK...",
    "fullName": "Node Owner",
    "email": "owner@example.com",
    "role": "owner"
  }
}
destroySelf#Allows a user to delete their own account within a specific blocklet. This action is irreversible.
Parameters
input
RequestTeamUserInput
required
An object containing the user's details for self-destruction.
2 subfields
Returns
user
UserInfo
The user object of the account that was deleted.
Example
import BlockletServerClient from '@blocklet/server-js';

// Assuming the client is authenticated as the user to be deleted
const client = new BlockletServerClient();

async function deleteMyAccount(userDid) {
  try {
    const { user } = await client.destroySelf({
      input: {
        teamDid: 'z1...',
        user: { did: userDid },
      },
    });
    console.log('User account deleted:', user.did);
  } catch (error) {
    console.error('Error deleting account:', error);
  }
}

deleteMyAccount('z8ia...'); // The DID of the currently authenticated user
Example Response
{
  "code": "ok",
  "user": {
    "did": "z8ia...",
    "fullName": "Former User"
  }
}
User Social Queries#getUserFollowers#Retrieves a list of users who are following a specified user.
Parameters
input
RequestUserRelationQueryInput
required
4 subfields
Returns
ResponseUserFollows
2 subfields
getUserFollowing#Retrieves a list of users that a specified user is following.
Parameters
input
RequestUserRelationQueryInput
required
4 subfields
Returns
ResponseUserFollows
2 subfields
getUserFollowStats#Retrieves follow-related statistics for one or more users, such as follower and following counts.
Parameters
input
RequestUserRelationCountInput
required
3 subfields
Returns
data
any
An object containing the follow statistics.
checkFollowing#Checks if a specific user is following one or more other users.
Parameters
input
RequestCheckFollowingInput
required
3 subfields
Returns
data
any
An object where keys are the `userDids` and values are booleans indicating the follow status.
getUserInvites#Retrieves a list of users invited by a specific user.
Parameters
input
RequestUserRelationQueryInput
required
3 subfields
Returns
ResponseUsers
An object containing the list of invited users and pagination information.
2 subfields
Roles & Permissions#getRoles#Retrieves a list of all available roles within a team or blocklet.
Parameters
input
TeamInput
required
An object containing the team DID.
1 subfields
Returns
roles
Role[]
An array of role objects.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRoles() {
  try {
    const { roles } = await client.getRoles({
      input: { teamDid: 'z1...' },
    });
    console.log('Available roles:', roles);
  } catch (error) {
    console.error('Error fetching roles:', error);
  }
}

fetchRoles();
Example Response
{
  "code": "ok",
  "roles": [
    { "name": "owner", "title": "Owner", "description": "Full access to all resources." },
    { "name": "admin", "title": "Administrator", "description": "Can manage users and settings." },
    { "name": "member", "title": "Member", "description": "Standard user access." },
    { "name": "guest", "title": "Guest", "description": "Limited access." }
  ]
}
getRole#Retrieves the details of a specific role by its name.
Parameters
input
RequestTeamRoleInput
required
An object containing the team DID and role name.
2 subfields
Returns
role
Role
The requested role object.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRoleDetails(roleName) {
  try {
    const { role } = await client.getRole({
      input: {
        teamDid: 'z1...',
        role: { name: roleName },
      },
    });
    console.log('Role details:', role);
  } catch (error) {
    console.error('Error fetching role details:', error);
  }
}

fetchRoleDetails('admin');
Example Response
{
  "code": "ok",
  "role": {
    "name": "admin",
    "title": "Administrator",
    "description": "Can manage users and settings.",
    "grants": ["user:create", "user:update", "setting:update"]
  }
}
getPermissions#Retrieves a list of all available permissions within a team or blocklet.
Parameters
input
TeamInput
required
An object containing the team DID.
1 subfields
Returns
permissions
Permission[]
An array of permission objects.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchPermissions() {
  try {
    const { permissions } = await client.getPermissions({
      input: { teamDid: 'z1...' },
    });
    console.log('Available permissions:', permissions);
  } catch (error) {
    console.error('Error fetching permissions:', error);
  }
}

fetchPermissions();
Example Response
{
  "code": "ok",
  "permissions": [
    { "name": "user:create", "description": "Allows creating new users." },
    { "name": "user:read", "description": "Allows viewing user profiles." },
    { "name": "post:publish", "description": "Allows publishing new posts." }
  ]
}
getPermissionsByRole#Retrieves the list of permissions associated with a specific role.
Parameters
input
RequestTeamRoleInput
required
An object containing the team DID and role name.
2 subfields
Returns
permissions
Permission[]
An array of permission objects associated with the role.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchRolePermissions(roleName) {
  try {
    const { permissions } = await client.getPermissionsByRole({
      input: {
        teamDid: 'z1...',
        role: { name: roleName },
      },
    });
    console.log(`Permissions for role '${roleName}':`, permissions);
  } catch (error) {
    console.error('Error fetching role permissions:', error);
  }
}

fetchRolePermissions('member');
Example Response
{
  "code": "ok",
  "permissions": [
    { "name": "post:create", "description": "Allows creating new posts." },
    { "name": "post:read", "description": "Allows reading posts." }
  ]
}
Invitations & Access Keys#getInvitations#Retrieves a list of all pending invitations for a team or blocklet.
Parameters
input
TeamInput
required
An object containing the team DID.
1 subfields
Returns
invitations
InviteInfo[]
An array of invitation objects.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchInvitations() {
  try {
    const { invitations } = await client.getInvitations({
      input: { teamDid: 'z1...' },
    });
    console.log('Pending invitations:', invitations);
  } catch (error) {
    console.error('Error fetching invitations:', error);
  }
}

fetchInvitations();
Example Response
{
  "code": "ok",
  "invitations": [
    {
      "inviteId": "...",
      "role": "member",
      "remark": "Invitation for new developer",
      "expireDate": "2024-12-31T23:59:59Z",
      "inviter": {
        "did": "z8ia...",
        "fullName": "Admin User"
      }
    }
  ]
}
getAccessKeys#Retrieves a list of access keys associated with a team or blocklet.
Parameters
input
RequestAccessKeysInput
required
An object containing query parameters for filtering access keys.
6 subfields
Returns
ResponseAccessKeys
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchAccessKeys() {
  try {
    const { list } = await client.getAccessKeys({
      input: {
        teamDid: 'z1...',
        paging: { pageSize: 20 },
      },
    });
    console.log('Access keys:', list);
  } catch (error) {
    console.error('Error fetching access keys:', error);
  }
}

fetchAccessKeys();
Example Response
{
  "code": "ok",
  "list": [
    {
      "accessKeyId": "...",
      "remark": "CI/CD Key",
      "createdAt": 1672531200,
      "lastUsedAt": 1675209600
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 20,
    "page": 1
  }
}
getAccessKey#Retrieves details for a single access key by its ID.
Parameters
input
RequestAccessKeyInput
required
An object containing the team DID and the access key ID.
2 subfields
Returns
data
AccessKey
The requested access key object.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchAccessKey(keyId) {
  try {
    const { data } = await client.getAccessKey({
      input: {
        teamDid: 'z1...',
        accessKeyId: keyId,
      },
    });
    console.log('Access key details:', data);
  } catch (error) {
    console.error('Error fetching access key:', error);
  }
}

fetchAccessKey('...'); // Replace with a valid access key ID
Example Response
{
  "code": "ok",
  "data": {
    "accessKeyId": "...",
    "accessKeyPublic": "...",
    "remark": "API access for integration tests",
    "createdAt": 1672531200
  }
}
Sessions#getSession#Retrieves details for a specific session by its ID.
Parameters
input
RequestGetSessionInput
required
An object containing the session ID.
1 subfields
Returns
session
any
The requested session object.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchSession(sessionId) {
  try {
    const { session } = await client.getSession({
      input: { id: sessionId },
    });
    console.log('Session details:', session);
  } catch (error) {
    console.error('Error fetching session:', error);
  }
}

fetchSession('...'); // Replace with a valid session ID
Example Response
{
  "code": "ok",
  "session": {
    "sessionId": "...",
    "userDid": "z8ia...",
    "status": "active",
    "createdAt": 1675209600
  }
}
getUserSessions#Retrieves a paginated list of sessions for a specific user.
Parameters
input
RequestUserSessionsInput
required
An object containing query parameters for user sessions.
3 subfields
Returns
ResponseUserSessions
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchUserSessions(userDid) {
  try {
    const { list, paging } = await client.getUserSessions({
      input: {
        teamDid: 'z1...',
        query: { userDid: userDid },
        paging: { pageSize: 5 },
      },
    });
    console.log('User sessions:', list);
  } catch (error) {
    console.error('Error fetching user sessions:', error);
  }
}

fetchUserSessions('z8ia...');
Example Response
{
  "code": "ok",
  "list": [
    {
      "id": "...",
      "userDid": "z8ia...",
      "status": "active",
      "lastLoginIp": "192.168.1.1",
      "createdAt": 1675209600
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 5,
    "page": 1
  }
}
getUserSessionsCount#Retrieves the total count of sessions for a specific user.
Parameters
input
RequestUserSessionsCountInput
required
An object containing query parameters for counting user sessions.
2 subfields
Returns
count
number
The total number of sessions for the user.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function countUserSessions(userDid) {
  try {
    const { count } = await client.getUserSessionsCount({
      input: {
        teamDid: 'z1...',
        query: { userDid: userDid },
      },
    });
    console.log('Total sessions for user:', count);
  } catch (error) {
    console.error('Error counting user sessions:', error);
  }
}

countUserSessions('z8ia...');
Example Response
{
  "code": "ok",
  "count": 5
}
Tags#getTags#Retrieves a paginated list of tags for a team or blocklet.
Parameters
input
RequestTagsInput
required
2 subfields
Returns
ResponseTags
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function fetchTags() {
  try {
    const { tags } = await client.getTags({
      input: {
        teamDid: 'z1...',
        paging: { pageSize: 100 },
      },
    });
    console.log('Available tags:', tags);
  } catch (error) {
    console.error('Error fetching tags:', error);
  }
}

fetchTags();
Example Response
{
  "code": "ok",
  "tags": [
    {
      "id": 1,
      "title": "Developer",
      "description": "Users with development access",
      "color": "#3498db"
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 100,
    "page": 1
  }
}
Overview

Getting Started

Authentication

API Reference

Advanced Usage

User & Access Management

User Queries#

getUsers#

getUser#

getUsersCount#

getUsersCountPerRole#

getOwner#

destroySelf#

getUserFollowers#

getUserFollowing#

getUserFollowStats#

checkFollowing#

getUserInvites#

Roles & Permissions#

getRoles#

getRole#

getPermissions#

getPermissionsByRole#

Invitations & Access Keys#

getInvitations#

getAccessKeys#

getAccessKey#

Sessions#

getSession#

getUserSessions#

getUserSessionsCount#

Tags#

getTags#

Node & Blocklet Management

Networking & Services
