Skip to main content

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.
    • teamDid string (required) — The DID of the blocklet or team.
    • query UserQueryInput — Filtering criteria for the user list.
    • sort UserSortInput — Sorting criteria for the user list.
    • paging PagingInput — Pagination options.
    • dids string[] — An array of user DIDs to retrieve specifically.

Returns

  • **** ResponseUsers — An object containing the list of users and pagination information.
    • users UserInfo[] — An array of user objects.
    • paging Paging — Pagination information for the result set.

Example

javascript
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);
  }
}

fetchUsers();

Example Response

json
{
  "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.
    • teamDid string (required) — The DID of the blocklet or team.
    • user UserInfoInput (required) — An object containing the user's DID. Only the did field is required.
      • did string (required)
    • options RequestTeamUserOptionsInput — Optional flags to include additional related data.
      • includeTags boolean — Whether to include the user's tags.
      • includePassports boolean — Whether to include the user's passports.
      • includeConnectedAccounts boolean — Whether to include the user's connected accounts.

Returns

  • user UserInfo — The requested user object.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)

Returns

  • count number — The total number of users.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)

Returns

  • counts KeyValue[] — An array of objects, where each object's key is the role name and value is the count.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)

Returns

  • user UserInfo — The owner's user object.

Example

javascript
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

json
{
  "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.
    • teamDid string (required) — The DID of the blocklet or team.
    • user UserInfoInput (required) — An object containing the user's DID. Only the did field is required.
      • did string (required)

Returns

  • user UserInfo — The user object of the account that was deleted.

Example

javascript
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

json
{
  "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)
    • teamDid string (required)
    • userDid string (required)
    • paging PagingInput
    • options QueryUserFollowOptionsInput

Returns

  • **** ResponseUserFollows
    • data UserFollows[]
    • paging Paging

getUserFollowing

Retrieves a list of users that a specified user is following.

Parameters

  • input RequestUserRelationQueryInput (required)
    • teamDid string (required)
    • userDid string (required)
    • paging PagingInput
    • options QueryUserFollowOptionsInput

Returns

  • **** ResponseUserFollows
    • data UserFollows[]
    • paging Paging

getUserFollowStats

Retrieves follow-related statistics for one or more users, such as follower and following counts.

Parameters

  • input RequestUserRelationCountInput (required)
    • teamDid string (required)
    • userDids string[] (required)
    • options QueryUserFollowStateOptionsInput

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)
    • teamDid string (required)
    • followerDid string (required) — The DID of the user who is potentially following others.
    • userDids string[] (required) — An array of DIDs to check if they are being followed.

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)
    • teamDid string (required)
    • userDid string (required) — The DID of the inviter.
    • paging PagingInput

Returns

  • **** ResponseUsers — An object containing the list of invited users and pagination information.
    • users UserInfo[]
    • paging Paging

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.
    • teamDid string (required)

Returns

  • roles Role[] — An array of role objects.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)
    • role RoleUpdateInput (required)
      • name string (required)

Returns

  • role Role — The requested role object.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)

Returns

  • permissions Permission[] — An array of permission objects.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)
    • role RoleUpdateInput (required)
      • name string (required)

Returns

  • permissions Permission[] — An array of permission objects associated with the role.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)

Returns

  • invitations InviteInfo[] — An array of invitation objects.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)
    • paging PagingInput
    • remark string
    • componentDid string
    • resourceType string
    • resourceId string

Returns

  • **** ResponseAccessKeys
    • list AccessKey[] — An array of access key objects.
    • paging Paging — Pagination information.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)
    • accessKeyId string (required)

Returns

  • data AccessKey — The requested access key object.

Example

javascript
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

json
{
  "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.
    • id string (required)

Returns

  • session any — The requested session object.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)
    • query UserSessionQueryInput
      • userDid string (required)
    • paging PagingInput

Returns

  • **** ResponseUserSessions
    • list UserSession[] — An array of session objects.
    • paging Paging — Pagination information.

Example

javascript
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

json
{
  "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.
    • teamDid string (required)
    • query UserSessionQueryInput
      • userDid string (required)

Returns

  • count number — The total number of sessions for the user.

Example

javascript
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

json
{
  "code": "ok",
  "count": 5
}

Tags

getTags

Retrieves a paginated list of tags for a team or blocklet.

Parameters

  • input RequestTagsInput (required)
    • teamDid string (required)
    • paging PagingInput

Returns

  • **** ResponseTags
    • tags Tag[] — An array of tag objects.
    • paging Paging — Pagination information.

Example

javascript
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

json
{
  "code": "ok",
  "tags": [
    {
      "id": 1,
      "title": "Developer",
      "description": "Users with development access",
      "color": "#3498db"
    }
  ],
  "paging": {
    "total": 1,
    "pageSize": 100,
    "page": 1
  }
}